Autodoc syntax¤

mkdocstrings works by processing special expressions in your Markdown files.

MKDoc is a web site building, serving and content management tool that has been designed to encourage the use of good information architecture and the production of accessible web sites.

The syntax is as follows:

1. Fantastic looking graphical. The first thing I’ll mention is that Material for MkDocs supports a variety.
2. Mkdocstrings can support multiple MkDocs themes. It currently supports supports the Material for MkDocs theme and, partially, the built-in ReadTheDocs theme. Each renderer can fallback to a particular theme when the user selected theme is not supported.
3. The migration process wasn't as easy as I'd hoped. I wanted all the old posts to move over, but there wasn't an easy path for my content prior to 2014. That's because some of those posts are in pure html and MkDocs only wants to deal in Markdown.
4. Example MkDocs site using GitLab Pages: https://pages.gitlab.io/mkdocs.

The identifier is a string identifying the object you want to document.The format of an identifier can vary from one handler to another.For example, the Python handler expects the full dotted-path to a Python object:my_package.my_module.MyClass.my_method.

The YAML block is optional, and contains some configuration options:

• handler: the name of the handler to use to collect and render this object. By default, it will use the value defined in the Global options's default_handler key, or 'python'.
• selection: a dictionary of options passed to the handler's collector. The collector is responsible for collecting the documentation from the source code. Therefore, selection options change how the documentation is collected from the source code.
• rendering: a dictionary of options passed to the handler's renderer. The renderer is responsible for rendering the documentation with Jinja2 templates. Therefore, rendering options affect how the selected object's documentation is rendered.

Every handler accepts at least these two keys, selection and rendering,and some handlers accept additional keys.Check the documentation for your handler of interest in Handlers.

Example with the Python handler

Documentation for MyClass

Print print print!

It is also possible to integrate a mkdocstrings identifier into a Markdown header:

The above is equivalent to:

Global options¤

mkdocstrings accepts a few top-level configuration options in mkdocs.yml:

• watch: a list of directories to watch while serving the documentation. See Watch directories.
• default_handler: the handler that is used by default when no handler is specified.
• custom_templates: the path to a directory containing custom templates. The path is relative to the docs directory. See Theming.
• handlers: the handlers global configuration.

Example:

mkdocs.yml

The handlers global configuration can then be overridden by local configurations:

Cross-references¤

Cross-references are written as Markdown reference-style links:

Any item that was inserted using the autodoc syntax(e.g. ::: full.path.object1) is possible to link to by using the same identifier with thecross-reference syntax ([example][full.path.object1]).But the cross-references are also applicable to the items' children that get pulled in.

Finding out the anchor¤

Mk Docs

If you're not sure which exact identifier a doc item uses, you can look at its 'anchor', which yourWeb browser will show in the URL bar when clicking an item's entry in the table of contents.If the URL is https://example.com/some/page.html#full.path.object1 then you know that this itemis possible to link to with [example][full.path.object1], regardless of the current page.

Cross-references to any Markdown heading¤

Changed in version 0.15

Linking to any Markdown heading used to be the default, but now opt-in is required.

If you want to link to any Markdown heading, not just mkdocstrings-inserted items, pleaseenable the autorefs plugin for MkDocs by addingautorefs to plugins:

mkdocs.yml

Mkdocs Vs Sphinx

Note that you don't need to (pip) install anything more; this plugin is guaranteed to be pulled in with mkdocstrings.

Example

Cross-references to a sub-heading in a docstring¤

New in version 0.14

If you have a Markdown heading inside your docstring, you can also link directly to it.In the example below you see the identifier to be linked is foo.bar--tips, because it's the 'Tips' heading that's part of the foo.bar object, joined with '--'.

Example

The above tip about Finding out the anchor also applies the same way here.

You may also notice that such a heading does not get rendered as a <h1> element directly, but rather the level gets shifted to fit the encompassing document structure. If you're curious about the implementation, check out mkdocstrings.handlers.rendering.HeadingShiftingTreeprocessor and others.

Paragraphs

Watch directories¤

You can add directories to watch with the watch key.It accepts a list of paths.

mkdocs.yml

When serving your documentationand a change occur in one of the listed path,MkDocs will rebuild the site and reload the current page.

Mkdocs Search

The watch feature doesn't have special effects.

Mkdocs Faq

Adding directories to the watch list doesn't have any other effect than watching for changes.For example, it will not tell the Python handler to look for packages in these paths(the paths are not added to the PYTHONPATH variable).If you want to tell Python where to look for packages and modules,see Python Handler: Finding modules.