Automatic documentation from sources, for MkDocs.
Project description
mkdocstrings
Automatic documentation from sources, for MkDocs. Come have a chat or ask questions on our Gitter channel.
Features - Requirements - Installation - Quick usage
Features
-
Language-agnostic: just like MkDocs, mkdocstrings is written in Python but is language-agnostic. It means you can use it with any programming language, as long as there is a handler for it. We currently have handlers for the Crystal and Python languages. Maybe you'd like to add another one to the list? :wink:
-
Multiple themes support: each handler can offer multiple themes. Currently, we offer the :star: Material theme :star: as well as basic support for the ReadTheDocs and MkDocs themes for the Python handler.
-
Cross-references across pages: mkdocstrings makes it possible to reference headings in other Markdown files with the classic Markdown linking syntax:
[identifier][]
or[title][identifier]
-- and you don't need to remember which exact page this object was on. This works for any heading that's produced by a mkdocstrings language handler, and you can opt to include any Markdown heading into the global referencing scheme.Note: in versions prior to 0.15 all Markdown headers were included, but now you need to opt in.
-
Cross-references across sites: similarly to Sphinx's intersphinx extension, mkdocstrings can reference API items from other libraries, given they provide an inventory and you load that inventory in your MkDocs configuration.
-
Inline injection in Markdown: instead of generating Markdown files, mkdocstrings allows you to inject documentation anywhere in your Markdown contents. The syntax is simple:
::: identifier
followed 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 mkdocstrings to add directories to be watched by MkDocs when serving the documentation, for auto-reload.
-
Reasonable defaults: you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
Requirements
mkdocstrings requires Python 3.7 or above.
To install Python 3.7, 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.7
pyenv install 3.7.12
# make it available globally
pyenv global system 3.7.12
Installation
With pip
:
pip install mkdocstrings
You can install support for specific languages using extras, for example:
pip install mkdocstrings[crystal,python]
See the available language handlers.
With conda
:
conda install -c conda-forge mkdocstrings
Quick usage
# mkdocs.yml
theme:
name: "material"
plugins:
- search
- mkdocstrings
In one of your markdown files:
# Reference
::: my_library.my_module.my_class
See the Usage section of the docs for more examples!
Project details
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
Built Distribution
Hashes for mkdocstrings-0.18.1-py3-none-any.whl
Algorithm | Hash digest | |
---|---|---|
SHA256 | 4053929356df8cd69ed32eef71d8f676a472ef72980c9ffd4f933ead1debcdad |
|
MD5 | 37ee3021ce46d9b6e9912188a467f87c |
|
BLAKE2b-256 | f4e8b3ff21aeaef6f5006f36aeba5a8de8fd941d3b334fcb1af991eeebd3a2cc |