mkdocstrings-python

A Python handler for mkdocstrings.

Requirements

mkdocstrings-python requires Python 3.7 or above.

To install Python 3.7, 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.7
pyenv install 3.7.12

# make it available globally
pyenv global system 3.7.12

Installation

You can install this handler as a mkdocstrings extra:

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings[python]>=0.18",
]

You can also explicitely depend on the handler:

# PEP 621 dependencies declaration
# adapt to your dependencies manager
[project]
dependencies = [
    "mkdocstrings-python",
]

Features

Data collection from source code: collection of the object-tree and the docstrings is done thanks to Griffe.
Support for type annotations: Griffe collects your type annotations and mkdocstrings uses them to display parameters types or return types. It is even able to automatically add cross-references to other objects from your API, from the standard library or from third-party libraries! See how to load inventories to enable it.
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 Griffe in modules, classes and even in __init__ methods.
Multiple docstring-styles support: common support for Google-style, Numpydoc-style, and Sphinx-style docstrings. See Griffe's documentation on docstrings support.
Admonition support in Google 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.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Uh oh!