From 2bbcbde0c6753f2a95a6005833c9ec143c4e8f7b Mon Sep 17 00:00:00 2001 From: abrichr Date: Tue, 21 Jul 2026 00:43:53 -0400 Subject: [PATCH] docs: refresh README for the openadapt-ops rename and docs pipeline Reframe the root README around what this repository now is: the source of truth for docs.openadapt.ai plus the ops automation that builds, validates, and publishes it. Note the former openadapt-maintenance name, describe the docs/, scripts/, tidy/, and repos.yml layout, give the local build/serve/ validate commands, and document the CI gate and the push-to-main plus dispatch/schedule GitHub Pages publish flow. Add the shared OpenAdapt positioning and cross-links to the flagship repo and live docs. Co-Authored-By: Claude Opus 4.8 Claude-Session: https://claude.ai/code/session_01NyCHrzA1psrKMFfroYbzaM --- README.md | 96 ++++++++++++++++++++++++++++++++++++++++--------------- 1 file changed, 71 insertions(+), 25 deletions(-) diff --git a/README.md b/README.md index 0b6f5a2..a5143bc 100644 --- a/README.md +++ b/README.md @@ -1,9 +1,13 @@ -# openadapt-maintenance +# openadapt-ops -Automated documentation generator for the OpenAdapt ecosystem. Syncs READMEs, aggregates changelogs, and generates digest pages using LLM. +Documentation source and ops automation for the OpenAdapt ecosystem. This +repository is the source of truth for the public product documentation at +[docs.openadapt.ai](https://docs.openadapt.ai), and it holds the tooling that +builds, validates, and publishes that site. -> **Lifecycle: Internal.** This repository is the publishing infrastructure and -> source for the public OpenAdapt documentation; it is not an end-user package. +> **Lifecycle: Internal.** This repository is publishing and operations +> infrastructure, not an end-user package. It was formerly named +> `openadapt-maintenance` and is now `OpenAdaptAI/openadapt-ops`. > **Source of truth:** This repository's `docs/` tree and `mkdocs.yml` own > `docs.openadapt.ai`. `OpenAdapt/docs`, `OpenAdapt/mkdocs.yml`, and @@ -11,38 +15,80 @@ Automated documentation generator for the OpenAdapt ecosystem. Syncs READMEs, ag > the production docs domain. See > [`docs/reference/documentation-governance.md`](docs/reference/documentation-governance.md). -## Quick Start +## About OpenAdapt -```bash -# Install dependencies -uv sync - -# Sync all READMEs into docs/ -python scripts/sync_readmes.py +OpenAdapt is a governed demonstration compiler. Record a GUI workflow once, +compile it, and replay it deterministically with zero model calls on the +healthy path. When the screen drifts, it re-resolves or proposes a governed +repair, verifies real effects, and halts rather than guesses. Every execution +substrate is first-class (web, native Windows, native macOS, Linux, RDP, and +Citrix/VDI), local-first with an optional managed cloud, and open-core under +MIT. The flagship code lives at +[github.com/OpenAdaptAI/openadapt](https://github.com/OpenAdaptAI/openadapt). -# Aggregate changelogs -python scripts/aggregate_changelog.py +## What is in this repository -# Generate What's New (optional: set ANTHROPIC_API_KEY for LLM summary) -python scripts/generate_whats_new.py +- **`docs/`** and **`mkdocs.yml`**: the curated MkDocs Material site published + to [docs.openadapt.ai](https://docs.openadapt.ai). Curated product pages own + the navigation. +- **`scripts/`**: the documentation pipeline. Mechanical sync steps + (`sync_readmes.py`, `aggregate_changelog.py`) are deterministic and make no + API calls. LLM-enhanced steps (`generate_whats_new.py`, + `build_architecture.py`) are optional and degrade gracefully without an API + key. `validate_docs.py` gates the site. +- **`tidy/`**: a CLI for scanning and scrubbing sensitive patterns from git + history and build artifacts (GitHub Releases, Actions, PyPI, and GHCR). See + [`tidy/README.md`](tidy/README.md). +- **`repos.yml`**: the list of ecosystem repositories the pipeline reads from. -# Build and preview the docs site -uv run mkdocs serve -``` +## Build the docs locally -## Adding a New Repo +```bash +# Install dependencies +uv sync --extra dev -Add an entry to `repos.yml` — no code changes needed. +# Preview the site with live reload +uv run mkdocs serve -## Architecture +# Build the site in strict mode (the same gate CI uses) +uv run mkdocs build --strict -- **Mechanical sync** (sync_readmes, aggregate_changelog): deterministic, no API calls -- **LLM-enhanced** (generate_whats_new, build_architecture): optional, gracefully degrades without API key -- **MkDocs Material**: builds to static site, deployable on GitHub Pages +# Validate the docs contract (empty-page check plus an mkdocs build) +uv run python scripts/validate_docs.py +``` ## Tests ```bash uv sync --extra dev -uv run pytest tests/ -v +uv run pytest tests/ -q ``` + +## Continuous integration and publishing + +- **`.github/workflows/ci.yml`** runs on every pull request and on push to + `main`. It installs locked dependencies, runs the test suite, validates the + documentation contract, and builds the site with `mkdocs build --strict`. +- **`.github/workflows/sync.yml`** builds and deploys the site to GitHub Pages, + served at `docs.openadapt.ai`. It runs when: + - a push to `main` touches `docs/**`, `mkdocs.yml`, or the workflow itself, + which builds and deploys this repository's docs as-is; + - a sub-repository dispatches a `repo-updated` event (see + [`.github/workflows/trigger.yml`](.github/workflows/trigger.yml)) so its + README and changelog pages re-sync here; + - the weekly schedule or a manual run performs a full cross-repo rebuild. + + Every path validates and builds in strict mode before deploying, so a failing + gate blocks publication. + +## Adding a new repository + +Add an entry to `repos.yml`. No code changes are needed. + +## Links + +- Live documentation: [docs.openadapt.ai](https://docs.openadapt.ai) +- Flagship repository: + [github.com/OpenAdaptAI/openadapt](https://github.com/OpenAdaptAI/openadapt) +- Documentation governance: + [`docs/reference/documentation-governance.md`](docs/reference/documentation-governance.md)