Problem
The project maintains per-app service_api/ reference docs by hand, documenting the public functions in each app's services.py. With 15 Django apps and a service layer convention that channels all database writes through services.py, keeping these references synchronized with the source is labor-intensive and error-prone. The review eval (Section 5.6) notes that the documentation corpus is "atypically mature" but the gap is in machine-verified freshness — there is no tooling to detect when a service function signature changes without a corresponding doc update. This creates a drift risk as the codebase grows.
Acceptance Criteria
Implementation Notes
Python's inspect module or AST parsing (ast.parse) can extract function signatures from each app's services.py. Consider using griffe or pdoc as a lightweight doc generator if custom AST walking is too brittle. The existing service_api/ docs follow a consistent markdown template — generate into the same format for a clean diff. A --check mode (exit non-zero if output differs from committed files) integrates cleanly into the existing CI pipeline at .github/workflows/actions.yml. The core.protocols module's @runtime_checkable DTO protocols (TrackerResult, ActivityRecord, IncrementalState) should also appear in the generated output since they define the service layer's data contracts.
References
- Eval finding: Test 16 (Documentation Completeness)
- Related files:
service_api/*.md, */services.py (15 apps), docs/Core_public_API.md, docs/Contributing.md, .github/workflows/actions.yml
Problem
The project maintains per-app
service_api/reference docs by hand, documenting the public functions in each app'sservices.py. With 15 Django apps and a service layer convention that channels all database writes throughservices.py, keeping these references synchronized with the source is labor-intensive and error-prone. The review eval (Section 5.6) notes that the documentation corpus is "atypically mature" but the gap is in machine-verified freshness — there is no tooling to detect when a service function signature changes without a corresponding doc update. This creates a drift risk as the codebase grows.Acceptance Criteria
scripts/generate_service_docs.py) introspects all*/services.pymodules, extracts public function signatures and docstrings, and generates markdown reference pagesservice_api/format (function name, parameters, return type, docstring summary)services.pychanges without a doc regenerationservice_api/is preserved where it adds context beyond what introspection captures (e.g., usage notes, cross-app dependency warnings)docs/Contributing.mdupdated to document the generation workflowImplementation Notes
Python's
inspectmodule or AST parsing (ast.parse) can extract function signatures from each app'sservices.py. Consider usinggriffeorpdocas a lightweight doc generator if custom AST walking is too brittle. The existingservice_api/docs follow a consistent markdown template — generate into the same format for a clean diff. A--checkmode (exit non-zero if output differs from committed files) integrates cleanly into the existing CI pipeline at.github/workflows/actions.yml. Thecore.protocolsmodule's@runtime_checkableDTO protocols (TrackerResult,ActivityRecord,IncrementalState) should also appear in the generated output since they define the service layer's data contracts.References
service_api/*.md,*/services.py(15 apps),docs/Core_public_API.md,docs/Contributing.md,.github/workflows/actions.yml