Skip to content

Latest commit

 

History

History
129 lines (94 loc) · 5.26 KB

README.md

File metadata and controls

129 lines (94 loc) · 5.26 KB
Raw

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? 😉

  • Multiple themes support: each handler can offer multiple themes. Currently, we offer the :star: Material theme ⭐ 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!