Living Documentation Toolkit

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).

---

• Overview
• Quickstart
• Documentation
• Services
• License

---

Overview

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

Quickstart

Installation

# 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

Example CLI Usage

# Normalize issues from collector output to PDF-ready format
living-doc normalize-issues \
  --input doc-issues.json \
  --output pdf_ready.json \
  --source auto \
  --document-title "Sprint 42 Report" \
  --document-version "1.0.0"

Documentation

Understand

• Architecture — System overview, data flow pipeline, package structure
• Contracts & Interfaces — CLI reference, input/output schemas, audit envelope, change control

Use

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.

Maintain

• Troubleshooting — Exit codes, common errors, FAQ
• Developer Guide — Environment setup, testing, linting, branch conventions
• Changelog — Version history and notable changes

Services

normalize-issues

Converts collector output (doc-issues.json) into PDF-ready canonical JSON (pdf_ready.json) compliant with the PDF generator specification.

• Cookbook — How detection, compatibility, and normalization work
• Recipe: Local usage — Run the CLI on your machine
• Recipe: GitHub Actions — CI/CD workflow integration

License

Licensed under the Apache License, Version 2.0. See LICENSE for full details.