Repository files navigation

Python handler formkdocstrings supporting relative cross-references.

mkdocstrings is an awesome plugin forMkDocs that can generate Markdown API documentationfrom comments in code. The standardpython handler allows you tocreate cross-reference links using the syntax[<title>][<path>] where the path musteither be the fully qualified name of the referent or is empty, in which case the pathis taken from the title. This works well when the names are short, but can be burdensomein larger codebases with deeply nested package structures.

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

classMyClass:defthis_method(self):"""        See [other_method][..] from [MyClass][(c)]        """

rather than:

classMyClass:defthis_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 referencesso that errors are easier to find and fix. For example:

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

For further details, please see theDocumentation