John Lancaster
64 lines
2.7 KiB
Markdown
64 lines
2.7 KiB
Markdown
# 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.
|