Skip to content

User Guide

Relative 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. If you work with long package and class names or with namespace packages, this can result in a lot of extra typing and harder to read doc-strings.

If you enable the relative_crossrefs option in the python_xref handler options in your mkdocs.yml file (see configuration for an example), then the handler will support more compact relative syntax:

class MyClass:
    def this_method(self):
        """
        See [other_method][mypkg.mymod.MyClass.other_method] 
        from [MyClass][mypkg.mymod.Myclass]
        """

class MyClass:
    def this_method(self):
        """
        See [other_method][..] from [MyClass][(c)]
        """

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 a single . then it will be expanded relative to the path of the doc-string in which it occurs.

  • 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. If there is only one module in the system it will be treated as a package.

  • If the path begins with one or more ^ characters, then will be replaced by the path of the parent element. For example, when used in a doc-string for a method, ^ would get replaced with the class and ^^ would get replaced with the module.

  • Similarly, if the path begins with two or more . characters, then all but the last . will be replaced by the parent element, and if nothing follows the last ., the title text will be appended according to the first rule.

    NOTE: When using either ^ or .. we have found that going up more than one or two levels makes cross-references difficult to read and should be avoided

These are demonstrated here:

class MyClass:
    def this_method(self):
        """
        [MyClass][^]
        Also [MyClass][(c)]
        [`that_method`][^.]
        Also [`that_method`][..]
        [init method][(c).__init__]
        [this module][(m)]
        [this package][(p)]
        [OtherClass][(m).]
        [some_func][^^.] or [some_func][...]
        """

class MyClass:
    def this_method(self):
        """
        [MyClass][mypkg.mymod.MyClass]
        Also [MyClass][mypkg.mymod.MyClass]
        [`that_method`][mypkg.mymod.MyClass.that_method]
        Also [`that_method`][mypkg.mymod.MyClass.that_method]
        [init method][mypkg.mymod.MyClass.__init__]
        [this module][mypkg.mymod]
        [this package][mypkg]
        [OtherClass][mypkg.mymod.OtherClass]
        [some_func][mypkg.mymod.some_func]
        """

This has been proposed as a feature in the standard python handler but has not yet been accepted.

Cross-reference checking

If relative_crossrefs and check_crossrefs are both enabled (the latter is true by default), then all cross-reference expressions will be checked to ensure that they exist and failures will be reported with the source location. Otherwise, missing cross-references will be reported by mkdocstrings without the source location, in which case it is often difficult to locate the source of the error. Note that the errors generated by this feature are in addition to the errors from mkdocstrings.

The current implementation of this feature can produce false errors for definitions from the python standard library. You can disable the check on a case-by-case basis by prefixing the reference expression with a ?, for example:

This function returns a [Path][?pathlib.] instance.