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.

Difference with mkdocstrings-python

mkdoctrings-python release 1.19 introduced support for relative (and also scoped) cross-references, but does not support the full range of relative syntax supported by this handler. Specifically, the standard handler only supports the leading . syntax described here.

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:

AbsoluteRelative

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:

RelativeAbsolute

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 (with the exception of any crossrefs which match a pattern in check_crossrefs_exclude). 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.

Migrating to standard mkdocstrings-python

If you want to migrate from this extension to the standard mkdocstrings-python handler, or just want to maintain compatibility with it, then you can use the compatibility_check and compatibility_patch options to help identify and convert incompatible cross-reference syntax.

The following syntax elements are specific to this extension and not supported by the standard handler:

Syntax	Description	Standard equivalent
^, ^^, ...	Caret parent specifier	.., ..., ... (dot prefix)
(c)	Class specifier	Equivalent number of leading dots
(m)	Module specifier	Equivalent number of leading dots
(p)	Package specifier	Equivalent number of leading dots
Trailing . after a name	Append title to reference	Expand title inline, e.g. [foo][bar.] → [foo][bar.foo]
Leading ?	Suppress reference checking	Remove the ?

To check for incompatibilities, set compatibility_check to "warn" or "error" in your handler options. To generate a patch file that converts all incompatible references to standard form, set compatibility_patch to a file path. See the configuration page for examples. Setting compatibility_patch implies a compatibility_check of "warn" if not set explicitly.