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
⭐ 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:
::: identifierfollowed 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:
pytkdocscollects 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
pytkdocsin modules, classes and even in__init__methods. -
Support for objects properties:
pytkdocsdetects if a method is astaticmethod, aclassmethod, 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. Note: only RST style is supported, not the whole markup.
-
Admonition support in docstrings: blocks like
Note:orWarning: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.
Roadmap
See the Feature Roadmap issue on the bugtracker.
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
This project currently only works with the Material theme of MkDocs. Therefore, it is required that you have it installed.
pip install mkdocs-material
Installation
With pip:
python3.6 -m pip install mkdocstrings
With conda:
conda install -c conda-forge mkdocstrings
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!
3 Oct 12, 2021
1 Jun 22, 2022
6 Nov 05, 2022
3 May 03, 2022
1.2k Dec 30, 2022
6 Dec 29, 2022
23.2k Dec 29, 2022
44 Dec 18, 2022
4 Dec 04, 2021
3 Jan 06, 2022
2.6k Jan 08, 2023
1 Jan 04, 2022
0 Sep 05, 2021
1 Nov 08, 2021
178 Dec 25, 2022
1 Dec 23, 2021
15 Oct 21, 2022
3 Sep 21, 2022
6 Nov 18, 2022
5 Oct 06, 2022