mkdocstrings¶

As of 0.0.11, Zensical provides preliminary support for mkdocstrings, which allows rendering API reference documentation from source code. We'll be rethinking API reference documentation from the ground up in the coming months, making it much more flexible and powerful.

Preliminary support

The mkdocstrings integration is preliminary, which means some features are not yet supported, specifically backlinks. We're working on bringing these features into Zensical.

Installation¶

mkdocstrings is not included with Zensical by default, so it needs to be installed separately:

with pipwith uv

pip install mkdocstrings-python

uv add mkdocstrings-python

Configuration¶

Configure mkdocstrings as a plugin:

zensical.tomlmkdocs.yml

[project.plugins.mkdocstrings.handlers.python]
inventories = ["https://docs.python.org/3/objects.inv"]
paths = ["src"]

[project.plugins.mkdocstrings.handlers.python.options]
docstring_style = "google"
inherited_members = true
show_source = false

plugins:
  - mkdocstrings:
      handlers:
        python:
          paths: [src]
          inventories:
            - https://docs.python.org/3/objects.inv
          options:
            docstring_style: google
            inherited_members: true
            show_source: false

The complete list of options can be found here:

Watching source files

While it is possible to configure search paths that are external to the docs project (outside of the parent directory containing the zensical.toml file) in the paths option of the Python handler, these external paths will not be watched for change, meaning that modifying files within them will not trigger a rebuild and reload. The reason is that the file agent will refuse to watch files that are outside the project folder for security reasons. We are working on lifting this limitation. You can follow progress on these backlog items: