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:
.md-content p {
padding-left: 30px;
}
.md-content ul {
padding-left: 20px !important;
}
.md-content h2 {
margin-top: 60px;
}
.md-content h3 {
margin-top: 40px;
}
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.4.0.tar.gz
(11.9 kB
view details)
Built Distribution
File details
Details for the file mkdocstrings-0.4.0.tar.gz.
File metadata
- Download URL: mkdocstrings-0.4.0.tar.gz
- Upload date:
- Size: 11.9 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 | c7939730ae76d26e437c86e090b210e6a0adbe9b8e2942a3bd97c4d039231e57 |
|
| MD5 | eb936651206e61842a913fd44386dbd2 |
|
| BLAKE2b-256 | 93b553b5942605109a0386921b21800aec164825dcb3cdb5ca145caba3a9988a |
File details
Details for the file mkdocstrings-0.4.0-py3-none-any.whl.
File metadata
- Download URL: mkdocstrings-0.4.0-py3-none-any.whl
- Upload date:
- Size: 13.3 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 | 5cb85da6bd8e878084b91d6f292bdcd75e4250556c90560648376cd42428a3f1 |
|
| MD5 | 2375f7d43364c325e2815902ea53a516 |
|
| BLAKE2b-256 | 56d1fd7c6ffdf9a3f538e3937bb6cee6ad8242e5e30dae0420ec023ef4796941 |
