Skip to content

Documentation

This guide outlines the documentation features included in the opentemplate template and available for your Python package.

Features

The template uses mkdocs ⧉ with various plugins for enhanced functionality:

  • Single source of truth – Both GitHub and mkdocs share the same markdown files (adjustable in mkdocs.yml and via content generation).
  • Automated Docs – Generates documentation from docstrings and /docs using mkdocstrings ⧉.
  • Modern Design – Uses mkdocs-material ⧉ for a polished look.
  • Auto Navigation – mkdocs-awesome-pages-plugin ⧉ builds the navigation structure.
  • Predefined Sections – docs includes structured folders (only visible in generated documentation if populated).
  • Versioning Support – mike ⧉ manages documentation versions.
  • GitHub Alerts – Use GitHub Alerts ⧉ to emphasize information (works in generated docs and docstrings!).

Tip

See mkdocs.yml for a full list of features.

Checks and fixers

  • Uses the same checks as in Prose (excluding auto-generated docstrings).
  • Runs a documentation build as a smoke test during commits.
  • Ensures docstrings coverage via interrogate ⧉ (default: 100%).
  • Detects common misspellings using codespell ⧉.

Important

Always review generated documentation manually before pushing changes.

Writing docstrings

  • Document every function, class, and module in your package.
  • Follow Google docstring style ⧉ for consistency.
  • Use <!-- mkdocs remove start --> and <!-- mkdocs remove end --> to exclude content from mkdocs (e.g. GitHub-only notes).
  • You can use absolute paths in the links, just like on GitHub, for example /docs/README.md will be transformed to mkdocs-compatible ../README.md if the link was specified in file /docs/tutorials/foo.md.

Adjustments

Common places to change documentation settings:

  • pyproject.toml – Configure plugins and tools in [dependency-groups] (dev-docs).
  • mkdocs.yml – General documentation settings.
  • docs/ – Add or modify content (not autogenerated).
  • /src docstrings – For API documentation.
  • Top-level *.md files – General project documentation (see nav in mkdocs.yml).

Caution

README.md in /docs serves as the documentation description, not the project overview.

Content generation

There might be cases where you want mkdocs documentation to differ from GitHub files (e.g. lack of support for certain features).

In this case, you can wrap the content you want to delete from mkdocs generated representation in <!-- mkdocs remove start --> and <!-- mkdocs remove end --> HTML/markdown comments.

Tip

Check README.md for an example.

Code sources

  • mkdocs.yml
  • pyproject.toml
  • docs/
  • docs/gen_ref_pages.py
  • .github/workflows/docs*.yml