Description
Limitations of absolute cross references
By default, mkdocstrings only supports cross-references where the path is
fully qualified or is empty, in which case it is taken from the title. But many times
you do not want to use fully qualified names everywhere in your doc strings, so you
must use the shorter name in the title and the full name in the path.
If you work with long package and class names or with namespace packages, this can result in a lot
of extra typing, harder to read doc-strings and more typographical errors.
For instance, here is a small example of what you need to do currently:
class MyClass:
def this_method(self):
"""
See [other_function][mypkg.mymod.MyClass.other_function]
from [MyClass][mypkg.mymod.Myclass]
"""Relative cross-references
I propose that we support a relative_crossrefs option, that when enabled would instruct the python handler
to substitute relative path expressions into absolute paths based on the known path of the doc-string in
which it occurs along with the text in the title. For instance, the previous example could be written as:
class MyClass:
def this_method(self):
"""
See [other_function][.] from [MyClass][^]
"""Relative path syntax
The relative path specifier has the following form:
-
If the path ends in
.then the title text will be appended to the path
(ignoring bold, italic or code markup). -
If the path begins with
.then it will be expanded relative to the path
of the doc-string in which it occurs. As a special case, if the current
doc-string is for a function or method, then.will instead be
expanded relative to the function's parent (i.e. the same as^.). -
If the path begins with
(c), that will be replaced by the path of the
class that contains the doc-string -
If the path begins with
(m), that will be replaced by the path of the
module that contains the doc-string -
if the path begins with
(p), that will be replaced by the path of the
package that contains the doc-string. For this purpose, a package is
a module that contains other modules or that does not have a parent
module. -
If the path begins with one or more
^characters, then that will go
up one level in the path of the current doc string for each^
Examples
Using relative syntax
class MyClass:
def this_method(self):
"""
[`that_method`][.]
[init method][(c).__init__]
[this module][(m)]
[OtherClass][(m).]
[some_func][^^.]
"""Using absolute syntax
class MyClass:
def this_method(self):
"""
[`that_method`][mypkg.mymod.MyClass.that_method]
[init method][mypkg.mymod.MyClass.__init__]
[this module][mypkg.mymod]
[OtherClass][mypkg.mymod.OtherClass]
[some_func][mypkg.mymod.some_func]
[
"""