Living Documentation Utilities

living-doc-utilities is the shared Python library for the Living Documentation ecosystem — the data models, serialization helpers, and GitHub utilities that the living-doc-* collectors and generators import instead of re-implementing.

Overview

The library provides the pieces every living-doc-* repository would otherwise duplicate:

• Structured data models — Issue and its subtypes (UserStoryIssue, FeatureIssue, FunctionalityIssue), the Issues collection, and ProjectStatus, so every action exchanges the same JSON shape.
• Serialization / deserialization (serde) — Issues.save_to_json() / Issues.load_from_json() and the IssueFactory that rebuilds the correct subtype by name.
• GitHub helpers — get_action_input() / set_action_output(), the GithubRateLimiter, and the safe_call_decorator retry wrapper.
• Shared plumbing — setup_logging(), the BaseActionInputs contract, and common constants.

It is designed to reduce duplication, improve testability, and simplify maintenance across the ecosystem.

Usage model. living-doc-utilities is consumed as a library by the other living-doc-* repos; it is not run directly. There is no CLI and no GitHub Action entry point in this repository — the collectors and generators depend on it as a pinned PyPI package and import from it.

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.

Usage

Prerequisites

Before installing this library, ensure you have:

• Python 3.10 or later
• pip package installer
• (Recommended) Virtual environment setup in your project

Installation

You can install the utilities locally, directly from GitHub, or from PyPI.

Option 1: Local Development (editable mode)

If you are developing the library alongside another project:

pip install -e ../living-doc-utilities

Make sure you activate the virtual environment in your main project before installing.

Option 2: From GitHub (using a release tag)

pip install git+https://github.com/AbsaOSS/living-doc-utilities@v0.4.0

Option 3: From PyPI

pip install living-doc-utilities

To pin a specific version:

pip install living-doc-utilities==0.4.0

Importing

from living_doc_utilities.model.issues import Issues
from living_doc_utilities.github.utils import get_action_input, set_action_output

issues = Issues.load_from_json("doc-issues.json")
print(issues.count())

Releasing

Releases run through a two-stage GitHub Actions pipeline. Stage 1 (.github/workflows/release_draft.yml, manual dispatch) runs the quality gate, tags the commit, and creates a draft GitHub release with generated notes — nothing irreversible. Stage 2 (.github/workflows/release.yml) fires when a maintainer publishes that draft release: it builds the package from the tag and uploads it to PyPI. Publishing the draft is the approval gate for the PyPI upload. No local tagging or manual upload is required. See the How to Release section of the Developer Guide for the step-by-step.

Developer Guide

See this Developer Guide for more technical, development-related information.

Contribution Guidelines

We welcome contributions to the Living Documentation ecosystem! Whether you're fixing bugs, improving documentation, or proposing new features, your help is appreciated.

How to Contribute

Before contributing, please review our contribution guidelines for more detailed information.

License Information

This project is licensed under the Apache License 2.0. It is a liberal license that allows you great freedom in using, modifying, and distributing this software, while also providing an express grant of patent rights from contributors to users.

For more details, see the LICENSE file in the repository.

Contact or Support Information

If you need help with using or contributing to the living-doc-utilities library, or if you have any questions or feedback, don't hesitate to reach out:

• Issue Tracker: For technical issues, feature requests, and general questions, use the GitHub Issues page.