| single |
# mkdocstrings
[ci]
[documentation]
[pypi version]
[conda version]
[gitpod]
[gitter]
Automatic documentation from sources, for [MkDocs].
Come have a chat or ask questions on our [Gitter channel].
---
**[Features]** - **[Requirements]** - **[Installation]** - **[Quick
usage]**
![mkdocstrings_gif1]
## 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.
## Installation
With `pip`:
`bash
pip install mkdocstrings
`
You can install support for specific languages using extras, for example:
```bash
pip install mkdocstrings[crystal,python]
```
See the [available language handlers].
With `conda`:
```bash
conda install -c conda-forge mkdocstrings
```
## Quick usage
|