better

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

@@ -0,0 +1,59 @@
+# 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.