mkdocstrings-python-xref

Python handler for mkdocstrings supporting relative cross-references.

mkdocstrings is an awesome plugin for MkDocs that can generate Markdown API documentation from comments in code. The standard python handler allows you to create cross-reference links using the syntax [<title>][<path>] where the path must either be the fully qualified name of the referent or is empty, in which case the path is taken from the title. This works well when the names are short, but can be burdensome in larger codebases with deeply nested package structures.

This package extends mkdocstrings-python to support a relative cross-reference syntax, that allows you to write doc-strings with cross-references like:

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

rather than:

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

Another benefit of this extension is that it will report source locations for bad references so that errors are easier to find and fix. For example:

$ mkdocs build
INFO    -  Cleaning site directory
INFO    -  Building documentation to directory: /home/jdoe/my-project/site
WARNING -  mkdocstrings_handlers: file:///home/jdoe/my-project/src/myproj/bar.py:16:
           Cannot load reference 'myproj.bar.bad'

For further details, please see the Documentation