A monorepo hosting multiple independent Python services that transform and enrich machine-readable artifacts produced by upstream collectors (e.g., living-doc-collector-gh) into datasets consumable by downstream actions (e.g., living-doc-generator-pdf).
This is a monorepo of multiple services and follows a different README shape than the single-purpose
living-doc-*action repos (per the fleet-widerepo-conventions.md). If you arrived from an action repo, theUnderstand / Use / Maintainlayout below is deliberate.
Expected usage: GitHub Actions first. The living-doc CLI is invoked as a step in a GitHub Actions workflow, chained between the upstream living-doc-* collector actions and the downstream generator actions. Running living-doc <service> locally — the pattern documented in DEVELOPER.md — is a development and debugging affordance only, not a second supported deployment target.
The Living Documentation pipeline runs AI-free. Every step — collect → normalize → generate — is deterministic tooling (Python, JSON Schema validation, Jinja2/Markdown templates) with no LLM call anywhere in that path. AbsaOSS/agentic-toolkit can accelerate the upstream authoring of GitHub Issues and .feature files, but it is never a runtime dependency of this pipeline: a human writing the same input by hand is a fully supported, identical path.
The Living Documentation Toolkit is a generic builder designed to:
- Host multiple independent services with CLI entrypoints
- Transform and normalize collector outputs into canonical datasets
- Provide adapters for input producer detection and parsing
- Offer reusable core utilities shared across services
- Enforce versioned contracts via JSON Schema and Pydantic models
# Clone the repository
git clone https://github.com/AbsaOSS/living-doc-toolkit.git
cd living-doc-toolkit
# Create and activate a virtual environment
python3 -m venv .venv
source .venv/bin/activate
# Install all packages
pip install --upgrade pip
pip install -r requirements.txt# Normalize issues from collector output to the canonical generator-ready dataset
living-doc normalize-issues \
--input doc-issues.json \
--output generator-ready.json \
--source auto \
--document-title "Sprint 42 Report" \
--document-version "1.0.0"
# Generate an AC-level test coverage matrix
living-doc coverage-matrix \
--doc-input doc-source.json \
--tests-input ui-tests.json \
--output coverage-matrix.json \
--fail-under 80The canonical output is
generator-ready.json. The legacy namepdf_ready.jsonis still accepted as a deprecated alias (normalize-issuesprints a notice when it is used).
- Architecture — System overview, data flow pipeline, package structure
- Contracts & Interfaces — CLI reference, input/output schemas, audit envelope, change control
- SPEC.md — How a new service or adapter is specced before it is built (the prospective-spec process for this monorepo)
Each service below has a Cookbook (explains how it works — detection logic, compatibility rules, normalization behavior) and Recipes (step-by-step guides to run it in a specific environment). See Services for the full list.
- Troubleshooting — Exit codes, common errors, FAQ
- Developer Guide — Environment setup, testing, linting, branch conventions
- Contribution Guidelines — How to report bugs, propose features, and open a PR
Converts collector output (doc-issues.json) into the canonical generator-ready.json dataset consumed by living-doc generators.
- Cookbook — How detection, compatibility, and normalization work
- Recipe: Local usage — Run the CLI on your machine
- Recipe: GitHub Actions — CI/CD workflow integration
Cross-references a doc-source.json (User Stories + acceptance criteria) with a ui-tests.json (E2E test scenarios) and produces coverage-matrix.json: an AC-level test coverage matrix per User Story.
- Package README — Matching logic, CLI reference, module layout
Licensed under the Apache License, Version 2.0. See LICENSE for full details.