Skip to content

Code-Heavy Documentation with mkdocstrings

Use this reference when your docs include API surfaces, function/class documentation, and source-driven technical reference.

Why mkdocstrings

mkdocstrings helps generate and maintain API reference pages directly from code and docstrings, reducing drift between implementation and docs.

Primary docs

When to Use It

  • You maintain Python modules/classes/functions that need searchable reference docs.
  • You want hand-written concept/task docs plus generated API reference pages.
  • You need consistent signatures, type hints, and docstring rendering.
  1. Hand-authored docs for concepts, architecture, and tasks.
  2. Generated docs (mkdocstrings) for API details.
  3. Cross-links in both directions:
  4. task pages link to specific API entries
  5. API pages link to practical guides and examples

Minimal Integration Pattern

  1. Add mkdocstrings and a Python handler package to project dependencies.
  2. Configure the Zensical docs toolchain to enable mkdocstrings within the site build.
  3. Create one API index page per package/domain.
  4. Expand coverage gradually from high-value modules first.

General reference examples

Compatibility

Zensical is generally expected to remain compatible with MkDocs-style configuration patterns, but prefer Zensical-native documentation and examples when they cover the same behavior.

Authoring Guidance for Docstrings

  • Begin with a one-line summary in imperative or descriptive form.
  • Document parameters, return values, raised exceptions, and side effects.
  • Include short examples for non-obvious usage.
  • Keep terminology aligned with task docs and architecture pages.

Quality Gates for Code-Heavy Docs

  • API pages build cleanly and include expected modules.
  • Symbols are grouped by domain, not dumped in one long page.
  • Public APIs have meaningful docstrings before publishing.
  • Generated reference pages are linked from user-facing docs.
  • Search can find both conceptual guides and concrete API entries.

Common Pitfalls

  • Treating generated API docs as a replacement for task documentation.
  • Publishing API pages without module-level context.
  • Letting undocumented public APIs accumulate.
  • Not reviewing generated pages after refactors.