Using sphinx-uml in auto-generated documentation

Using Sphinx templates, one can call the uml directive in the auto-generated documentation pages.

Extensions (docs/conf.py)

Enable the following extensions:

extensions = [
    "sphinx.ext.autodoc",
    "sphinx.ext.autosummary",
    "sphinx.ext.napoleon",
     # ...
    "sphinx.ext.graphviz",  # https://stackoverflow.com/a/59319659/14851404
    "sphinx_uml"
]

Templates

Sphinx templates are used to customize how Sphinx generate package and module pages. Otherwise, Sphinx use its own default templates.

Custom templates are usually stored in docs/_templates. They are typically based on sphinx/templates/apidoc/*jinja files. See example/docs/_templates as an example.

Building the documentation

To be taken into account, the --templatedir option is needed when building the documentation. See example/Makefile:

Example:

poetry run sphinx-apidoc -f -o docs/ src/ --separate --templatedir=docs/_templates
poetry run sphinx-build -b html docs/ docs/_build/html

See example/docs/_templates and example/Makefile as an example.