mkdocstrings

Automatic documentation from sources, for MkDocs.
Come have a chat or ask questions on our Gitter channel.
Features - 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
C,
Crystal,
Python,
TypeScript, and
VBA languages,
as well as for shell scripts/libraries.
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.
-
Reasonable defaults:
you should be able to just drop the plugin in your configuration and enjoy your auto-generated docs.
Used by
mkdocstrings is used by well-known companies, projects and scientific teams:
Ansible,
Apache,
FastAPI,
Google,
IBM,
Jitsi,
Microsoft,
NVIDIA,
Prefect,
Pydantic,
Textual,
and more...
Installation
The mkdocstrings
package doesn't provide support for any language: it's just a common base for language handlers.
It means you likely want to install it with one or more official handlers, using extras.
For example, to install it with Python support:
pip install 'mkdocstrings[python]'
Alternatively, you can directly install the language handlers themselves,
which depend on mkdocstrings
anyway:
pip install mkdocstrings-python
This will give you more control over the accepted range of versions for the handlers themselves.
See the official language handlers.
With conda
:
conda install -c conda-forge mkdocstrings mkdocstrings-python
Quick usage
In mkdocs.yml
:
site_name: "My Library"
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!