OpenRath Documentation

This repository publishes version-matched documentation for OpenRath. The main branch tracks the current stable documentation, while annotated tags pair each documentation snapshot with the same tag in the sibling OpenRath repository.

Version policy

• main: current stable docs (v2.0.0 at this update).
• v1.0.0 through v2.0.0: immutable local documentation snapshots paired with matching OpenRath code tags.
• archive/pre-versioning-2026-07-11: the pre-versioning documentation state.

No permanent future-version or maintenance branch is required for the current workflow. Start one only when real concurrent work makes it necessary.

Local preview

Install the documentation dependencies in the sibling code repository once:

cd ../OpenRath
uv sync --group docs
cd ../OpenRath-Docs

Build all seven versions and start a local server:

make versions
make serve

Open http://localhost:8000/. The root redirects to stable/ (v2.0.0), and the navigation switcher can move between every tagged version.

Useful commands:

make html                         # strict current-version build
make versions                     # build all tagged versions
make versions VERSIONS="v1.3.0 v2.0.0"
make list-versions
make clean

See versioning/README.md for builder details. Generated HTML lives under _build/ and is not committed.

GitHub Pages

Every push to main runs docs-pages.yml, builds all configured versions, strictly rebuilds the Stable version, and deploys the generated Sphinx site to GitHub Pages. The workflow uses GitHub's reported Pages base path, so version switching works from the default /OpenRath-Docs/ project URL as well as from a root-mounted site.

Until the final OpenRath v2.0.0 tag exists, the workflow builds the Stable documentation against v2.0.0rc1. Once the final tag is published, the same workflow automatically uses the matching Stable source tag.