Skip to content

SUMMARY_REPORT.md

Latest commit

 

History

History
109 lines (85 loc) · 5.07 KB

SUMMARY_REPORT.md

File metadata and controls

109 lines (85 loc) · 5.07 KB

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