mkdocs-terok

Shared ProperDocs documentation generators for terok projects.

Provides reusable modules for generating CI workflow maps, integration test maps, module maps, code metrics reports, API reference pages, and config reference documentation from Pydantic models. A built-in terok ProperDocs plugin drives every generator except the config reference (which needs a consumer-supplied Pydantic model); the generator modules themselves never import the doc engine and can also be used standalone via mkdocs-gen-files shims.

The metrics report module can optionally parse output from scc, complexipy, tach, vulture, and docstr-coverage. When any of these tools is absent, the corresponding report section degrades gracefully to a warning.

Installation

Add to your project as a docs-build dependency.

pip:

pip install mkdocs-terok

uv — pyproject.toml (PEP 735 dependency group):

[dependency-groups]
docs = [
    "mkdocs-terok~=0.8.0",
]

The package installs ProperDocs and its core generator dependencies. Config reference generation additionally requires consumer-supplied Pydantic v2. Consumers must declare their theme and additional plugins in their own docs requirements. This repository's docs group requires mkdocs-material>=9.8.0; that group and its lockfile are not installed with the published package. Upgrading mkdocs-terok alone does not upgrade Material in a consumer's lockfile.

Configuration

Configured via the terok plugin in your properdocs.yml. See this repository's own properdocs.yml for a self-documenting example that exercises most of the generators the package ships.

License

0BSD — use freely, no strings attached.