John Lancaster
60 lines
2.4 KiB
Markdown
60 lines
2.4 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 docs toolchain to enable mkdocstrings plugin/extension.
|
|
3. Create one API index page per package/domain.
|
|
4. Expand coverage gradually from high-value modules first.
|
|
|
|
General reference examples:
|
|
- Plugin docs: https://www.mkdocs.org/user-guide/plugins/
|
|
- Material + code/reference setup concepts: https://squidfunk.github.io/mkdocs-material/reference/
|
|
|
|
## 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.
|