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
- January-March 2020: Big refactor.
- March-April 2020: Write. Tests. Because. It's important. Gather feedback about Python handler configuration options. Work the backlog.
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
!!! note 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.0.tar.gz
(24.9 kB
view details)
Built Distribution
File details
Details for the file mkdocstrings-0.11.0.tar.gz.
File metadata
- Download URL: mkdocstrings-0.11.0.tar.gz
- Upload date:
- Size: 24.9 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.5 CPython/3.8.2 Linux/5.6.6-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 144da162dde45d8245f4d68e919951ff3e4a2f1c5d0dedf458db40f23878fc8a |
|
| MD5 | de38b98105551619161b115507539b37 |
|
| BLAKE2b-256 | 3331c4b9127f296eaefc2c26cb32720781245c45aec2b6e229edebda2f2c8020 |
File details
Details for the file mkdocstrings-0.11.0-py3-none-any.whl.
File metadata
- Download URL: mkdocstrings-0.11.0-py3-none-any.whl
- Upload date:
- Size: 32.6 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: poetry/1.0.5 CPython/3.8.2 Linux/5.6.6-arch1-1
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 3ef5465d2432d4a17cc822810fa5993019e608428cef050ce75c41bedfc295e0 |
|
| MD5 | 9d7f997470e40edf95deff7cbebf11f6 |
|
| BLAKE2b-256 | 996d536c951485257d5af53fa0835c296c25f5d36d7a23df60b4497ef0a2e602 |
