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:
Features
- Works great with Material theme:
mkdocstringswas designed to work best with the great Material theme. - Support for type annotations:
mkdocstringsuses your type annotations to display parameters types or return types. - Recursive documentation of Python objects: just write the module dotted-path, and you get the full module docs. No need to ask for each class, function, etc.
- Support for documented attribute: attributes (variables) followed by a docstring (triple-quoted string) will
be recognized by
mkdocstrings, in modules, classes and even in__init__methods. - Support for objects properties:
mkdocstringswill know if a method is astaticmethod, aclassmethodor else, it will also know if a property is read-only or writable, and more! These properties will be displayed next to the object signature. - Every object has a TOC entry and a unique permalink: the navigation is greatly improved! Click the anchor next to the object signature to get its permalink, which is its Python dotted-path.
- Auto-reference other objects:
mkdocstringsmakes it possible to reference other Python objects from your markdown files, and even from your docstrings, with the classic Markdown syntax:[this object][package.module.object]or directly with[package.module.object][]. - Google-style sections support in docstrings:
mkdocstringsunderstandsArguments:,Raises:andReturns:sections. It will even keep the section order in the generated docs. - Support for source code display:
mkdocstringscan add a collapsible div containing the source code of the Python object, directly below its signature, with the right line numbers. - Admonition support in docstrings: blocks like
Note:orWarning:will be transformed to their admonition equivalent. We do not support nested admonitions in docstrings! - Sane defaults: you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
- Configurable: (soon)
mkdocstringsis configurable globally, and per autodoc instruction.
To get an example of what is possible, check mkdocstrings'
own documentation, generated with itself.
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
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
In one of your markdown files:
# 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 in docs/custom.css:
div.autodoc {
padding-left: 25px;
border-left: 4px solid rgba(230, 230, 230);
}
And add it to your configuration:
extra_css:
- custom.css
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.6.0.tar.gz
(16.7 kB
view details)
Built Distribution
File details
Details for the file mkdocstrings-0.6.0.tar.gz.
File metadata
- Download URL: mkdocstrings-0.6.0.tar.gz
- Upload date:
- Size: 16.7 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 | 32af515a4e51d179be8dfedbeb10b8cd19738724a2daeee72b3db8876b48021a |
|
| MD5 | ab2b0f9f2e49b9eadcb363f2fbda21f3 |
|
| BLAKE2b-256 | 6dae5a60ef74d369a025374b1f9d2a7b5c31fb4092202782ac9c99bee1432415 |
File details
Details for the file mkdocstrings-0.6.0-py3-none-any.whl.
File metadata
- Download URL: mkdocstrings-0.6.0-py3-none-any.whl
- Upload date:
- Size: 19.0 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 | 235e716693047ea20f3acd9fb47eab0592c56a96147fa3f000e85af7703e91d6 |
|
| MD5 | 668aeaa8e2df9ae136da9dfe60bd7273 |
|
| BLAKE2b-256 | 2efc3195f582f3a0d079f64f3f5cd4259806b3f295ad0c6977171ab117ce61e4 |
