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);
}
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 details)
Built Distribution
File details
Details for the file mkdocstrings-0.5.0.tar.gz.
File metadata
- Download URL: mkdocstrings-0.5.0.tar.gz
- Upload date:
- Size: 12.1 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.0 CPython/3.6.9 Linux/5.4.3-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 5f2d833e4d32ef1814c2f778c0fa091ca083bedd6487b86706ea4b7fb8abc1b5 |
|
| MD5 | 691c638757f853c193c39ad04fd0cdd6 |
|
| BLAKE2b-256 | beba9db484b75f12c8f7c9560eb9f2713a2cb9f21f3272c9e392fc8a831c1239 |
File details
Details for the file mkdocstrings-0.5.0-py3-none-any.whl.
File metadata
- Download URL: mkdocstrings-0.5.0-py3-none-any.whl
- Upload date:
- Size: 13.5 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.0 CPython/3.6.9 Linux/5.4.3-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 0eddbcccae33c1e8d2313a87b1d1b474a4760c601d7e463af668c51ad4ec0088 |
|
| MD5 | 1e4a23cb3ce32f42004c96ff95205c82 |
|
| BLAKE2b-256 | 9010199e95b8bc1f236a4b4abe9de12a6b5d63cd5158fa89e55ce6e74880987c |
