prompts/docs/skills/zensical-docs/references/code-heavy-docs-and-mkdocstrings.md

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:

• mkdocstrings home: https://mkdocstrings.github.io/
• mkdocstrings Python handler: https://mkdocstrings.github.io/python/
• Griffe (Python parsing engine): https://mkdocstrings.github.io/griffe/

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.

Recommended Documentation Split

1. Hand-authored docs for concepts, architecture, and tasks.
2. Generated docs (mkdocstrings) for API details.
3. Cross-links in both directions:
   • task pages link to specific API entries
   • 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:

• Zensical docs home and setup entry point: https://zensical.org/docs/
• Zensical code blocks and authoring patterns: https://zensical.org/docs/authoring/code-blocks/
• Zensical customization overview: https://zensical.org/docs/customization/

Compatibility note:

• 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.