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

!!! info "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.

!!! info "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/)

!!! note "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.