Documenting a Python package with mkdocs-material

This article shows how to create a Python package documentation with code reference via mkdocs-material. This documentation framework is beautiful out of the box, powerful but simple to configure and customise, and it uses Markdown! It offers a great alternative to the popular Sphinx docs.

Python package docs with code reference, created with mkdocs-material and mkdocstrings

There are a lot of useful tools and services to document a software project. However, when it comes to documenting a Python package with an automated code reference (extracting the docstrings of classes and functions of your package), the selection is more limited. As packages are frequently updated, creating the code reference manually is not a good option.

The most commonly used tool for this in the Python community is Sphinx, often styled with the familiar readthedocs theme. Sphinx is very mature, offering a ton of features and extensions. However, setup, configuration and writing the docs in the .rst (restructuredText) file format can feel unintuitive and a bit finicky. For a more in-depth break-down of the advantages and tradeoffs using Sphinx see here.

mkdocs material

More recently, mkdocs material has seen a huge surge in popularity as the documentation tool of choice for many projects. The following tweet of Sebastián Ramírez, the developer of FastAPI, sums it up well:

A few examples of documentations created with mkdocs-material:

Code reference with mkdocs

Setting up your documentation with mkdocs-material is a pretty simple process, just follow the instructions in the official documentation. Everything is configured in the mkdocs.yml file in your projects top-folder. Here, I just want to focus on adding the code reference of your Python package using the mkdocstrings plugin.

IMPORTANT! mkdocstrings currently only accepts Google style docstrings!

Setup

First install the mkdocstrings plugin:

pip install mkdocstrings[python]

Activate the plugin by adding it to the plugin section in the mkdocs.yml configuration file:

# mkdocs.yml
theme:
  name: "material"

plugins:
  - search
  - mkdocstrings

Add the code reference

Lets say our fictitious “my-package” Python package has the following structure, and we want to add the code reference for the “workflow” module.

First, create a new markdown file “workflow-reference” in the docs folder:

Add the following text to the markdown file. This will automatically add all classes and functions within the workflow.py module to the code reference:

# Workflow module
::: my-package.workflow

(Optional) You can also include or exclude only specific elements:

# Workflow class
::: my-package.workflow.Workflow
::: my-package.workflow.get_workflows

Now list the “docs/workflow-reference.md” file as a new chapter in the table of contents in the mkdocs.yml configuration file:

nav:
    - Home: index.md
    - Installation: installation.md
    - Code Reference:
        - Workflow: workflow-reference.md

Check the result in your browser with the mkdocs preview function mkdocs serve.

mkdocstrings automatically extracts the docstrings (Google style!), displays the parameters & types in a nicely formatted table, is able to pick up admonitions & examples, and can show a foldable button to quickly see the underlying source code of the function.

For live examples of a code reference check out the official mkdocstrings documentation or the the UP42 Python SDK code reference.

CLI reference

If your Python package contains a CLI (command line interface) created with click, you can use mkdocs-click to automate the CLI reference. See here for a live example and the underlying code, which is just as simple to use as mkdocstrings.

mkdocs-material with mkdocstrings is a fantastic choice to document your Python package. The community is growing rapidly and the packages are constantly improved further.

You can follow me on chrieke.com and Twitter @ chrieke