mkdocstrings 0.3.0

Automatic documentation from docstrings, for mkdocs.

mkdocstrings

Automatic documentation from docstrings, for mkdocs.

This plugin is still in alpha status. Here is how it looks with the mkdocs-material theme for now:

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

Installation

With pip:

python3.6 -m pip install mkdocstrings

With pipx:

python3.6 -m pip install --user pipx

pipx install --python python3.6 mkdocstrings

Usage

# mkdocs.yml

# designed to work best with material theme
theme:
  name: "material"

# these extensions are required for best results
markdown_extensions:
  - admonition
  - codehilite
  - attr_list
  - pymdownx.details
  - pymdownx.superfences
  - pymdownx.inlinehilite
  - toc:
      permalink: true

plugins:
  - search
  - mkdocstrings

# Reference

::: my_library.my_module.my_class

You can reference objects from other modules in your docstrings:

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:

.md-content p {
  padding-left: 30px;
}

.md-content ul {
  padding-left: 20px !important;
}

.md-content h2 {
  margin-top: 60px;
}

.md-content h3 {
  margin-top: 40px;
}