A Python handler for mkdocstrings.
Project description
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:
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.
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Hashes for mkdocstrings-python-0.6.6.tar.gz
Algorithm | Hash digest | |
---|---|---|
SHA256 | 37281696b9f199624ae420e0625b6659b7fdfbea736618bce7fd978682dea3b1 |
|
MD5 | 0962a617e99c45f5ff7c8d55b75faea3 |
|
BLAKE2b-256 | f81570beb7c41684e4a2328fe5b4cc2b5ab96f7f2c3e21edcd99aa76af3a6d57 |
Hashes for mkdocstrings_python-0.6.6-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | c118438d3cb4b14c492a51d109f4e5b27ab06ba19b099d624430dfd904926152 |
|
MD5 | 97dc43c327d7738b7deb0eace3f6eff3 |
|
BLAKE2b-256 | bb830f47c94ab1afc3726e9bc72359e59e3a00a4c57c4f9c6962feda1bd21797 |