mkdocstrings

mkdocstrings is a library to automatically generate mkdocs pages from the code docstrings.

Install⚑

pip install mkdocstrings

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

plugins:
  - mkdocstrings

Usage⚑

MkDocstrings works by processing special expressions in your Markdown files.

The syntax is as follow:

::: identifier
    YAML block

The identifier is a string identifying the object you want to document. The format of an identifier can vary from one handler to another. For example, the Python handler expects the full dotted-path to a Python object: my_package.my_module.MyClass.my_method.

The YAML block is optional, and contains some configuration options:

• handler: the name of the handler to use to collect and render this object.
• selection: a dictionary of options passed to the handler's collector. The collector is responsible for collecting the documentation from the source code. Therefore, selection options change how the documentation is collected from the source code.
• rendering: a dictionary of options passed to the handler's renderer. The renderer is responsible for rendering the documentation with Jinja2 templates. Therefore, rendering options affect how the selected object's documentation is rendered.

# Documentation for `MyClass`

::: my_package.my_module.MyClass
    handler: python
    selection:
      members:
        - method_a
        - method_b
    rendering:
      show_root_heading: false
      show_source: false

nav:
  - "My page": my_page.md

class MyClass:
    """Print print print!"""

    def method_a(self):
        """Print A!"""
        print("A!")

    def method_b(self):
        """Print B!"""
        print("B!")

    def method_c(self):
        """Print C!"""
        print("C!")

Reference the objects in the documentation⚑

With a custom title:
[`Object 1`][full.path.object1]

With the identifier as title:
[full.path.object2][]

Global options⚑

MkDocstrings accept a few top-level configuration options in mkdocs.yml:

• default_handler: the handler that is used by default when no handler is specified.
• custom_templates: the path to a directory containing custom templates. The path is relative to the docs directory. See Customization.
• handlers: the handlers global configuration.

Example:

plugins:
- mkdocstrings:
    default_handler: python
    handlers:
      python:
        rendering:
          show_source: false
    custom_templates: templates
watch:
  - src/my_package

Where watch is a list of directories to watch while serving the documentation. So if any file is changed in those directories, the documentation is rebuilt.

The handlers global configuration can then be overridden by local configurations:

::: my_package.my_module.MyClass
    rendering:
      show_source: true

Check the Python handler options for more details.

References⚑

• Docs