diff --git a/SUMMARY_REPORT.md b/SUMMARY_REPORT.md deleted file mode 100644 index f69d067..0000000 --- a/SUMMARY_REPORT.md +++ /dev/null @@ -1,109 +0,0 @@ -# openadapt-maintenance — Implementation Summary - -## What Was Implemented - -A complete, working documentation generator for the OpenAdapt ecosystem following the **Option D (Hybrid)** design — mechanical sync for per-package pages + optional LLM for synthesis pages. - -### Scripts (5 files, ~250 lines total) - -| Script | Lines | Purpose | -|--------|-------|---------| -| `scripts/sync_readmes.py` | 55 | Fetch READMEs from GitHub, render per-package doc pages via Jinja2 | -| `scripts/aggregate_changelog.py` | 48 | Fetch GitHub releases, produce unified changelog | -| `scripts/generate_whats_new.py` | 78 | Collect merged PRs via `gh` CLI, optionally summarize with LLM | -| `scripts/build_architecture.py` | 68 | Generate architecture overview (static fallback or LLM-enhanced) | -| `scripts/validate_docs.py` | 38 | Check for empty pages, run `mkdocs build --strict` | - -### Configuration - -- `repos.yml` — 10 repos configured with categories (core/devtools) -- `mkdocs.yml` — MkDocs Material with dark/light theme, search, code copy -- `pyproject.toml` — Dependencies: mkdocs-material, jinja2, pyyaml, requests; optional: anthropic - -### Templates & Prompts - -- `templates/package_page.md.j2` — Per-package page template with badges, sync timestamp -- `templates/whats_new.md.j2` — What's New template with fallback (raw PR list if no LLM) -- `prompts/whats_new.txt` — LLM prompt for digest generation -- `prompts/architecture.txt` — LLM prompt for architecture overview - -### GitHub Actions Workflows - -- `.github/workflows/sync.yml` — Main workflow (repository_dispatch + weekly cron + manual) -- `.github/workflows/trigger.yml` — Template for sub-repos to send dispatch events - -### Docs Site Pages - -- `docs/index.md` — Landing page with package table -- `docs/whats-new.md` — Auto-generated (placeholder until first run) -- `docs/changelog.md` — Auto-generated (placeholder until first run) -- `docs/architecture.md` — Auto-generated (placeholder until first run) - -## Test Results - -**17/17 tests passing** - -``` -tests/test_sync_readmes.py::test_load_repos PASSED -tests/test_sync_readmes.py::test_sync_renders_pages PASSED -tests/test_sync_readmes.py::test_sync_creates_directories PASSED -tests/test_sync_readmes.py::test_fetch_readme_handles_failure PASSED -tests/test_sync_readmes.py::test_sync_all_repos_artifact PASSED -tests/test_aggregate_changelog.py::test_aggregate_writes_changelog PASSED -tests/test_aggregate_changelog.py::test_aggregate_skips_drafts PASSED -tests/test_aggregate_changelog.py::test_aggregate_handles_no_releases PASSED -tests/test_aggregate_changelog.py::test_fetch_releases_handles_http_error PASSED -tests/test_generate_whats_new.py::test_generate_without_llm PASSED -tests/test_generate_whats_new.py::test_generate_with_no_prs PASSED -tests/test_generate_whats_new.py::test_llm_summarize_no_api_key PASSED -tests/test_generate_whats_new.py::test_llm_summarize_no_anthropic_package PASSED -tests/test_generate_whats_new.py::test_generate_writes_artifact PASSED -tests/test_validate_docs.py::test_check_empty_pages_finds_issues PASSED -tests/test_validate_docs.py::test_check_empty_pages_no_issues PASSED -tests/test_validate_docs.py::test_check_empty_pages_nested PASSED -``` - -## Generated Artifacts - -Real docs generated from live GitHub data: - -``` -tests/artifacts/generated_docs/ -├── architecture.md (1.5 KB — static overview, 2 categories) -├── changelog.md (2.5 KB — 5 repos with releases) -├── index.md (1.3 KB — package table) -├── whats-new.md (6.3 KB — 44 merged PRs across 8 repos) -├── MANIFEST.txt -└── packages/ - ├── openadapt.md (16 KB) - ├── openadapt-ml.md (11 KB) - ├── openadapt-evals.md (19 KB) - ├── openadapt-capture.md (8 KB) - ├── openadapt-desktop.md (9 KB) - ├── openadapt-flow.md (0.5 KB — repo has no README) - ├── openadapt-consilium.md (9 KB) - ├── openadapt-wright.md (7 KB) - ├── openadapt-herald.md (5 KB) - └── openadapt-crier.md (4 KB) -``` - -MkDocs site builds successfully (`mkdocs build` exits 0). Warnings are expected — relative links in READMEs point to repo-internal files. - -## What's Left To Do - -1. **Create GitHub repo**: `gh repo create OpenAdaptAI/openadapt-maintenance --public` -2. **Push code**: `git remote add origin ... && git push -u origin main` -3. **Set up GitHub Pages**: Settings → Pages → Deploy from branch (gh-pages) -4. **Add `ANTHROPIC_API_KEY` secret** for LLM-enhanced pages -5. **Configure DNS**: Point `docs.openadapt.ai` to GitHub Pages -6. **Add trigger workflows** to sub-repos (copy `.github/workflows/trigger.yml`) -7. **Create `DOCS_DISPATCH_TOKEN`** (fine-grained PAT with repo scope) -8. **Add to website**: Link from openadapt-web to docs.openadapt.ai - -## LLM Integration - -All LLM features gracefully degrade without `ANTHROPIC_API_KEY`: -- `generate_whats_new.py` → outputs raw PR list instead of summarized digest -- `build_architecture.py` → outputs static package list instead of narrative overview - -When API key is set, uses `claude-haiku-4-5-20251001` for cost efficiency (~$0.50-2/month).