Living Documentation Utilities

Purpose

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.

Contents

• Overview
• Usage tip
• Where next
• Developer guide
• Contributing
• License
• Contact

Overview

• 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

Usage tip

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 sanitiser

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

Where next

Developer guide

Setup, quality gates, regeneration, release and documentation rules: DEVELOPER.md.

Contributing

Issues, branches, pull requests and the AI-free principle: CONTRIBUTING.md.

License

Apache License 2.0; see LICENSE.

Contact

Questions, bugs and feature requests: GitHub Issues.