living-doc-utilities is the shared Python library of the Living Documentation ecosystem. The living-doc-*
collectors, transforms and generators import it as a pinned PyPI package; it has no CLI and no GitHub Action.
This page gives the overview, a usage tip, and the page to read next.
- Contracts (
living_doc_utilities.contracts): typed models of the six documentation contracts, their JSON Schemas, and the helpers every component shares → Documentation contracts - Authoring (
living_doc_utilities.authoring): normalisation, the acceptance-criterion grammar, and the parsers for every authoring surface → Authoring - GitHub (
living_doc_utilities.github): action input and output, a rate limiter, a call decorator that never swallows a failure → GitHub helpers - Inputs (
living_doc_utilities.inputs): a base class for a GitHub Action's inputs → Action inputs and logging - Runtime helpers:
setup_logging()and shared constants → Action inputs and logging - AI-free: every pipeline step is deterministic tooling, with no LLM call → AI-free principle
Python 3.10 or later. Pin the version exactly, and add an extra only for the module that needs it:
pip install "living-doc-utilities==0.5.0" # contracts, authoring, github.utils, inputs
pip install "living-doc-utilities[github]==0.5.0" # adds the GitHub rate limiter and decorators
pip install "living-doc-utilities[html]==0.5.0" # adds the HTML sanitiserfrom living_doc_utilities.contracts.io import read_artifact, write_artifact
from living_doc_utilities.contracts.testing import full_sample
write_artifact(full_sample("doc-entities-v1.0.0"), "doc-entities.json")
result = read_artifact("doc-entities.json", expected="doc-entities")
assert result.schema_version == "doc-entities-v1.0.0"Which module needs which extra: Extras. Pinning rules: Versioning.
| I want to… | Read |
|---|---|
| find a module and what it needs installed | API |
| read or write a contract file | Documentation contracts |
| parse authored documents | Authoring |
| look up an error or warning code | Errors and warnings |
| set up the repository, run the gates, release | Developer guide |
| contribute a change | Contributing |
Setup, quality gates, regeneration, release and documentation rules: DEVELOPER.md.
Issues, branches, pull requests and the AI-free principle: CONTRIBUTING.md.
Apache License 2.0; see LICENSE.
Questions, bugs and feature requests: GitHub Issues.