mkdocstrings

Automatic documentation from sources, for MkDocs.

Features - Python handler - Requirements - Installation - Quick usage

Features

Language-agnostic: just like MkDocs, mkdocstrings is written in Python but is language-agnostic. It means you can use it with any programming language, as long as there is a handler for it. The Python handler is built-in. Others are external. Maybe you'd like to add another one to the list? 😉
Multiple themes support: each handler can offer multiple themes. Currently, we offer the :star: Material theme ⭐ as well as basic support for the ReadTheDocs theme for the Python handler.
Cross-links across pages: mkdocstrings makes it possible to reference headings in other Markdown files with the classic Markdown linking syntax: [identifier][] or [title][identifier] -- and you don't need to remember which exact page this object was on. This works for any heading that's produced by a mkdocstrings language handler, and you can opt to include any Markdown heading into the global referencing scheme.

Note: in versions prior to 0.15 all Markdown headers were included, but now you need to opt in.
Inline injection in Markdown: instead of generating Markdown files, mkdocstrings allows you to inject documentation anywhere in your Markdown contents. The syntax is simple: ::: identifier followed by a 4-spaces indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler to collect and render documentation.
Global and local configuration: each handler can be configured globally in mkdocs.yml, and locally for each "autodoc" instruction.
Watch source code directories: you can tell mkdocstrings to add directories to be watched by MkDocs when serving the documentation, for auto-reload.
Reasonable defaults: you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.

Python handler

Data collection from source code: collection of the object-tree and the docstrings is done by pytkdocs.
Support for type annotations: pytkdocs collects your type annotations and mkdocstrings uses them to display parameters types or return types.
Recursive documentation of Python objects: just use the module dotted-path as identifier, and you get the full module docs. You don't need to inject documentation for each class, function, etc.
Support for documented attributes: attributes (variables) followed by a docstring (triple-quoted string) will be recognized by pytkdocs in modules, classes and even in __init__ methods.
Support for objects properties: pytkdocs detects if a method is a staticmethod, a classmethod, etc., it also detects if a property is read-only or writable, and more! These properties will be displayed next to the object signature by mkdocstrings.
Multiple docstring-styles support: almost complete support for Google-style, Numpy-style, and reStructuredText-style docstrings. Notes: only RST style is supported, not the whole markup. Numpy-style requires an extra dependency from pytkdocs: pytkdocs[numpy-style].
Admonition support in docstrings: blocks like Note: or Warning: will be transformed to their admonition equivalent. We do not support nested admonitions in docstrings!
Every object has a TOC entry: we render a heading for each object, meaning MkDocs picks them into the Table of Contents, which is nicely display by the Material theme. Thanks to mkdocstrings cross-reference ability, you can reference other objects within your docstrings, with the classic Markdown syntax: [this object][package.module.object] or directly with [package.module.object][]
Source code display: mkdocstrings can add a collapsible div containing the highlighted source code of the Python object.

Requirements

mkdocstrings requires Python 3.6 or above.

To install Python 3.6, I recommend using pyenv.

# install pyenv
git clone https://github.com/pyenv/pyenv ~/.pyenv

# setup pyenv (you should also put these three lines in .bashrc or similar)
export PATH="${HOME}/.pyenv/bin:${PATH}"
export PYENV_ROOT="${HOME}/.pyenv"
eval "$(pyenv init -)"

# install Python 3.6
pyenv install 3.6.12

# make it available globally
pyenv global system 3.6.12

Installation

With pip:

pip install mkdocstrings

With conda:

conda install -c conda-forge mkdocstrings

Note for Python: you'll need an extra dependency to parse Numpy-style docstrings:

pip install pytkdocs[numpy-style]

Quick usage

# mkdocs.yml
theme:
  name: "material"

plugins:
- search
- mkdocstrings

In one of your markdown files:

# Reference

::: my_library.my_module.my_class

See the Usage section of the docs for more examples!

stanbiryukov / mkdocstrings