Automatic documentation from docstrings, for mkdocs.
Project description
mkdocstrings
Automatic documentation from docstrings, for mkdocs.
This plugin is still in alpha status. Here is how it looks with the mkdocs-material theme for now:
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.8
# make it available globally
pyenv global system 3.6.8
Installation
With pip
:
python3.6 -m pip install mkdocstrings
With pipx
:
python3.6 -m pip install --user pipx
pipx install --python python3.6 mkdocstrings
Usage
# mkdocs.yml
# designed to work best with material theme
theme:
name: "material"
# these extensions are required for best results
markdown_extensions:
- admonition
- codehilite
- attr_list
- pymdownx.details
- pymdownx.superfences
- pymdownx.inlinehilite
- toc:
permalink: true
plugins:
- search
- mkdocstrings
# Reference
::: my_library.my_module.my_class
You can reference objects from other modules in your docstrings:
def some_function():
"""
This is my function.
It references [another function][package.submodule.function].
It also references another object directly: [package.submodule.SuperClass][].
"""
pass
Add some style:
div.autodoc {
padding-left: 25px;
border-left: 4px solid rgba(230, 230, 230);
}
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
mkdocstrings-0.5.0.tar.gz
(12.1 kB
view hashes)
Built Distribution
Close
Hashes for mkdocstrings-0.5.0-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 0eddbcccae33c1e8d2313a87b1d1b474a4760c601d7e463af668c51ad4ec0088 |
|
MD5 | 1e4a23cb3ce32f42004c96ff95205c82 |
|
BLAKE2b-256 | 9010199e95b8bc1f236a4b4abe9de12a6b5d63cd5158fa89e55ce6e74880987c |