mkdocs-terok¶

Shared ProperDocs documentation generators for terok projects.

Overview¶

mkdocs-terok is a terok ProperDocs plugin containing several documentation generators. For advanced use cases the generator modules are public and can be called directly via mkdocs-gen-files.

Quick start — plugin¶

# properdocs.yml
plugins:
  - search
  - terok:
      ci_map: true
      code_metrics: true
      test_map: true
      ref_pages: true

All generators default to false (opt-in). CSS and JS assets are injected automatically unless inject_css / inject_js are set to false.

For a complete, real-world example see this repository's own properdocs.yml — it drives the very documentation site you are reading.

Quick start — generator API¶

Each module produces Markdown strings or structured results that consumers wrap in thin mkdocs-gen-files callbacks:

from mkdocs_terok.ci_map import generate_ci_map

markdown = generate_ci_map()

The generators have no runtime dependency on the doc engine — they handle content generation only.

Modules¶

Module	Purpose
`mkdocs_terok`	Package root — exports `brand_css_path()`, `mermaid_zoom_js_path()`, and `INVENTORY_ONLY_ENV`
`mkdocs_terok.plugin`	ProperDocs `BasePlugin` wrapping all generators
`mkdocs_terok.ref_pages`	Generate API reference pages from source tree
`mkdocs_terok.ci_map`	Parse and visualize GitHub Actions workflows
`mkdocs_terok.code_metrics`	Code quality analysis — optionally parses output from scc, complexipy, tach, vulture, and docstr-coverage (sections degrade gracefully when tools are absent)
`mkdocs_terok.test_map`	Generate test suite maps with marker extraction
`mkdocs_terok.module_map`	Module and class docstrings grouped by layer (`tach.toml`-aware)
`mkdocs_terok.config_reference`	Render Pydantic models as config documentation
`mkdocs_terok.inventory`	Build the repo's `objects.inv` without needing sibling inventories
`mkdocs_terok.versions`	Assemble the versioned docs tree from release snapshots — see Versioned docs publishing

Dogfooding¶

This documentation site uses mkdocs-terok on itself: the CI map, code metrics, test map, and reference page generators run via the terok plugin, and the config reference renderers run via a mkdocs-gen-files script — see properdocs.yml on master for the full live configuration.

Config Reference Demo¶

The Config Reference Demo uses a Pydantic model for a space weather monitoring station to exercise all three renderers (render_model_tables, render_yaml_example, render_json_schema) — it remains as a mkdocs-gen-files script since it requires a consumer-specific Pydantic model.