Automatic documentation from sources, for MkDocs.
Project description
mkdocstrings
Automatic documentation from sources, for MkDocs.
Features
- Language agnostic: just like
mkdocs,mkdocstringsis written in Python but is language-agnostic. It means you can use it for any language, as long as you implement ahandlerfor it. Currently, we only have a Python handler. Maybe you'd like to contribute another one :wink:? - Multiple themes support: each handler can offer multiple themes. Currently, we only offer the :star: Material theme :star: for the Python handler.
- Cross-references to other objects:
mkdocstringsmakes it possible to reference other headings from your Markdown files with the classic Markdown syntax:[identifier][]or[title][identifier]. This feature is language agnostic as well: you can cross-reference any heading that appear in your Markdown pages. If the handler for a particular language renders headings for documented objects, you'll be able to reference them! - Inline injection in Markdown: instead of generating Markdown files,
mkdocstringsallows you to inject documentation anywhere in your Markdown contents. The syntax is simple:::: identifierfollowed by a 4-spaces indented YAML block. The identifier and YAML configuration will be passed to the appropriate handler to collect and render documentation. - Global and local configuration: each handler can be configured globally in
mkdocs.yml, and locally for each "autodoc" instruction. - Watch source code directories: you can tell
mkdocstringsto add directories to be watched bymkdocswhen serving the documentation, for auto-reload. - Sane defaults: you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
Python handler features
- Data collection from source code: collection of the object-tree and the docstrings is done by
pytkdocs. The following features are possible thanks to it:- Support for type annotations:
pytkdocscollects your type annotations andmkdocstringsuses them to display parameters types or return types. - Recursive documentation of Python objects: just use the module dotted-path as identifier, and you get the full module docs. You don't need to inject documentation for each class, function, etc.
- Support for documented attribute: attributes (variables) followed by a docstring (triple-quoted string) will
be recognized by
pytkdocsin modules, classes and even in__init__methods. - Support for objects properties:
pytkdocsdetects if a method is astaticmethod, aclassmethod, etc., it also detects if a property is read-only or writable, and more! These properties will be displayed next to the object signature bymkdocstrings. - Google-style sections support in docstrings:
pytkdocsunderstandsArguments:,Raises:andReturns:sections, and returns structured data formkdocstringsto render them. - Admonition support in docstrings: blocks like
Note:orWarning:will be transformed to their admonition equivalent. We do not support nested admonitions in docstrings!
- Support for type annotations:
- Every object has a TOC entry: we render a heading for each object, meaning
mkdocspicks them into the Table of Contents, which is nicely display by the Material theme. Thanks tomkdocstringscross-reference ability, you can even reference other objects within your docstrings, with the classic Markdown syntax:[this object][package.module.object]or directly with[package.module.object][] - Source code display:
mkdocstringscan add a collapsible div containing the highlighted source code of the Python object.
To get an example of what is possible, check mkdocstrings'
own documentation, auto-generated from sources by itself of course,
and the following GIF:
Roadmap
- December-January 2020: Proof of Concept.
- January-March 2020: Refactor.
- March-April 2020: Test suite for
pytkdocs. Bug fixes, enhancements. - May-June 2020: Test suite for
mkdocstringsitself. Better documentation. Maybe a second handler, just for the fun.
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
This project currently only works with the Material theme of MkDocs. Therefore, it is required that you have it installed.
pip install mkdocs-material
Installation
With pip:
python3.6 -m pip install mkdocstrings
Usage
# mkdocs.yml
theme:
name: "material"
plugins:
- search
- mkdocstrings:
default_handler: python
handlers:
python:
rendering:
show_source: true
watch:
- src/my_library
In one of your markdown files:
# Reference
::: my_library.my_module.my_class
rendering:
show_source: false
::: org.jpackage.BestOfTheBestFactoryInterface
handler: java # we don't have a java handler yet, it's just an example
In documentation strings (written in Markdown), you can reference objects from other places:
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.doc-contents:not(.first) {
padding-left: 25px;
border-left: 4px solid rgba(230, 230, 230);
margin-bottom: 80px;
}
And add it to your mkdocs.yml:
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.11.1.tar.gz
(25.0 kB
view details)
Built Distribution
File details
Details for the file mkdocstrings-0.11.1.tar.gz.
File metadata
- Download URL: mkdocstrings-0.11.1.tar.gz
- Upload date:
- Size: 25.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.5 CPython/3.8.2 Linux/5.6.11-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 93bbc68c0ef787a73f6b200df02ce3bc4494b40f454069e304acc1b49cdd79f3 |
|
| MD5 | 8be5961e41c28bdd33817ade2a9b1b0d |
|
| BLAKE2b-256 | caed8c5dd3ef74cc037f788b9bbb9d7de4184251107baaeb83d007f70e2dd031 |
File details
Details for the file mkdocstrings-0.11.1-py3-none-any.whl.
File metadata
- Download URL: mkdocstrings-0.11.1-py3-none-any.whl
- Upload date:
- Size: 32.7 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.5 CPython/3.8.2 Linux/5.6.11-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 467521e66a0e3500b3623575a62eba4dfff2d60a79b9fe5169a3e0310864bab6 |
|
| MD5 | e75da0442ccb7c84f3c3353aa69490ab |
|
| BLAKE2b-256 | 843a5938e1b52b45998171f72af634a8f8ccebd8f6303ed9d7359336f7bad3b7 |
