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.3.0.tar.gz
(10.8 kB
view details)
Built Distribution
File details
Details for the file mkdocstrings-0.3.0.tar.gz.
File metadata
- Download URL: mkdocstrings-0.3.0.tar.gz
- Upload date:
- Size: 10.8 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 | 167627ce0ded0965cdc9eacebb8dee91e62fce3eaf1f3500db2623cadcc76977 |
|
| MD5 | f90a1e3fe8861330990d93a1a79be82a |
|
| BLAKE2b-256 | ab15c991fe0e7ec7a42c0a6d56497642f29561a93a195ea31928e9b523467528 |
Provenance
File details
Details for the file mkdocstrings-0.3.0-py3-none-any.whl.
File metadata
- Download URL: mkdocstrings-0.3.0-py3-none-any.whl
- Upload date:
- Size: 12.2 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 | a53a3ba4a2b7ba64274a792fd8b7b25f2a71918a0929766939e24624918c7ddd |
|
| MD5 | 0cef20dce8d1f33eab472ebbce193d29 |
|
| BLAKE2b-256 | 3569ca54155ceb5b01e0091d8aeb4a1f8fe1835df6edbbe880396382365ea63e |
