Documentation Quality

Best practices for docstrings, README files and inline documentation quality gates.

Back

Strong documentation ensures that mgpy CLI, API and release artifacts all tell the same story. Missing documentation creates support and integration cost.

Key points

CLI: On Windows the examples use the recommended py -3.12 -m <module> ... form (for example py -3.12 -m manifestguard ...). On Linux/macOS this usually maps to python3.12 -m ....
README, installation guide and docstrings must describe the same entry path.
Public APIs should document return values, failure cases and example invocations.
Documentation belongs in the release pipeline, not in aftercare after a merge.

Recommended mgpy workflow

Document the public CLI and API paths that external users actually see first.
Add implementation detail, ADR and special workflow material afterwards.
Before a release, verify that README, INSTALLATION and CI examples still show the same commands.

Quick start

py -3.12 -m manifestguard check --extended
py -3.12 -m manifestguard schema --output openapi.json
py -3.12 run_manifestguard.py --report .manifestguard/manifestguard-report.json