Skip to content

Feature Plan: Science ADK Documentation Site (adk.dev-style)

Status: Proposed · Owner: TBD · Target: science-adk.dev (or twmmason.github.io/science-adk)

1. Context

Today all Science ADK documentation lives in a 335-line README.md, two loose files in docs/ (adk-foundation.md, naming.md), seven skills/*/SKILL.md files, and one rules/scientific-integrity.md. There is no navigation, no search, no API reference, and no versioning. As the CLI surface (15 commands), the primitive set (7 agents), and the skills library grow, the README is becoming the bottleneck for adoption.

adk.dev (Google ADK docs) is the reference target: a MkDocs Material site published to GitHub Pages, with a landing page, a "Get Started" funnel, conceptual guides, tutorials, an auto-generated Python API reference (mkdocstrings), full-text search, light/dark theme, and a version selector (mike).

2. Goals

  1. A published static documentation site with the same information architecture quality as adk.dev.
  2. Single source of truth: docs live in-repo as Markdown, reviewed via PR.
  3. Zero-drift API reference — generated from docstrings in python/src/science_adk/, not hand-written.
  4. Every code block in Get Started is executable and CI-verified.
  5. Deployed automatically on merge to main; versioned on tag.

Non-goals

  • Dynamic/interactive playground or hosted notebooks (later).
  • Localisation (structure should not preclude it).
  • Migrating the README away — the README stays as the GitHub landing page but is trimmed to an overview plus links into the site.

3. Technology choice

Concern Choice Why
Generator MkDocs + Material for MkDocs Exactly what adk.dev uses; Python-native, matching this repo's Python core.
API reference mkdocstrings[python] Generates reference pages from docstrings/type hints.
Versioning mike Standard MkDocs versioning, publishes to gh-pages.
Diagrams Mermaid via pymdownx.superfences The README already uses Mermaid DAGs.
Hosting GitHub Pages from gh-pages branch Free, already a GitHub-hosted project; custom domain via CNAME.
Link/build checks mkdocs build --strict + lychee link checker in CI Fail the build on broken nav/links.

Rejected: Docusaurus (adds a Node toolchain and duplicates the Python docstring problem), Sphinx (heavier authoring, weaker default UX).

4. Information architecture

Home (landing page)
├── Get Started
│   ├── Installation
│   ├── Quickstart — Kepler in 30 seconds
│   ├── Your first research project
│   └── Installing skills into your coding agent
├── Concepts
│   ├── Why Science ADK (from README overview)
│   ├── Built on Google ADK (from docs/adk-foundation.md)
│   ├── The research workspace (GOAL.md / HYPOTHESIS.md / workflow.json / runs)
│   ├── Typed ports and dataflow contracts
│   ├── Agent primitives (Config, Data, Training, Algorithm, Evaluation,
│   │   Visualization, Composite)
│   ├── Provenance ledger and dataset references
│   ├── Deterministic integrity gates
│   ├── The three-pillar audit
│   └── Naming conventions (from docs/naming.md)
├── Guides
│   ├── Writing an agent node
│   ├── Writing and registering tools
│   ├── Using MCP servers (stdio + HTTP)
│   ├── Validating a workflow
│   ├── Running, re-running (--reuse), and reading a trace
│   ├── Auditing, reporting, and campaigns
│   └── Evolving experiments and recording learnings
├── Examples
│   └── Kepler's Third Law from the NASA Exoplanet Archive
├── Skills (one page per skills/*/SKILL.md, rendered in place)
│   ├── research · experiment-design · agent-authoring
│   └── debugging · optimizing · evolving · auditing
├── Reference
│   ├── CLI reference (all 15 commands, generated from argparse)
│   ├── Python API (mkdocstrings: agent, primitives, tools, datasets,
│   │   models, runner, score, validate, report, workspace)
│   ├── science.toml reference
│   └── workflow.json schema reference
└── Community
    ├── Contributing · Code of Conduct · Security · License

5. Repository layout

mkdocs.yml                  # site config + nav
docs/
  index.md                  # landing page (hero, feature grid, CTA)
  get-started/*.md
  concepts/*.md
  guides/*.md
  examples/kepler.md
  skills/*.md               # thin includes of ../skills/<name>/SKILL.md
  reference/
    cli.md                  # generated by scripts/gen_cli_reference.py
    api/*.md                # mkdocstrings ::: directives
    science-toml.md
    workflow-json.md
  community/*.md
  stylesheets/extra.css     # brand colours, hero styling
  assets/                   # logo, favicon, social card, diagrams
scripts/
  gen_cli_reference.py      # argparse -> Markdown
  gen_api_nav.py            # optional: mkdocs-gen-files hook
.github/workflows/docs.yml  # build on PR, deploy on main/tag
python/pyproject.toml       # [project.optional-dependencies] docs = [...]

Existing docs/adk-foundation.md and docs/naming.md move into docs/concepts/ with redirects (mkdocs-redirects) so existing links survive.

6. Landing page (docs/index.md)

Mirrors the adk.dev hero pattern:

  1. Hero — "Build, execute, and audit autonomous scientific research." Two CTAs: Get Started and View on GitHub.
  2. 30-second proof — the Kepler tabbed code block (bash) with its real output (recovered exponent 1.4555 vs theoretical 1.5000).
  3. Feature grid (Material cards): Native Google ADK · Deterministic gates · Provenance ledger · Typed DAG validation · Git-native workspace · MCP tool integration.
  4. Architecture Mermaid DAG (reuse the README graph).
  5. Next steps links into Get Started / Concepts / Examples.

7. Implementation phases

Phase 1 — Scaffold and publish (thin but live)

  • Add mkdocs.yml with Material theme, nav skeleton, Mermaid, search, light/dark palette toggle, repo link, edit-this-page.
  • Add docs extra to python/pyproject.toml (mkdocs-material, mkdocstrings[python], mike, mkdocs-gen-files, mkdocs-literate-nav, mkdocs-redirects).
  • Write docs/index.md landing page + docs/stylesheets/extra.css.
  • Move adk-foundation.md, naming.md into concepts/ with redirects.
  • .github/workflows/docs.yml: mkdocs build --strict on PR; mike deploy --push --update-aliases <version> latest on main.
  • Enable GitHub Pages on gh-pages; add CNAME if a domain is acquired.
  • Exit criteria: site is live, landing page + existing docs reachable.

Phase 2 — Get Started + Concepts

  • Split the README's Quickstart and "How to investigate any question" into get-started/ pages, one command-step per page section.
  • Author the nine Concepts pages, each ≤ 800 words with one diagram or code sample; lift accurate prose from README/adk-foundation.
  • Trim README to overview + links (keep badges, Kepler teaser, license).
  • Exit criteria: a new user can go from zero to a scored run using the site alone.

Phase 3 — Reference (generated)

  • scripts/gen_cli_reference.py: walk the argparse tree in python/src/science_adk/cli.py, emit docs/reference/cli.md with usage, flags, and examples per command. Run via mkdocs-gen-files so it regenerates on every build (no committed drift).
  • mkdocstrings pages for each public module; enforce Google-style docstrings; add a ruff pydocstyle (D) rule set to CI for science_adk/primitives and top-level modules.
  • Hand-write science.toml and workflow.json schema references, with a JSON Schema published under docs/assets/schema/.
  • Exit criteria: every public symbol and every CLI command is documented and mkdocs build --strict passes with no missing-reference warnings.

Phase 4 — Guides, Examples, Skills

  • Seven task-oriented guides (see IA), each ending in a verifiable output.
  • Full Kepler walkthrough page: DAG, each agent file annotated, the provenance-gate fabrication test from CI, and the interpretation of the 1.4555 exponent.
  • Skills pages generated from skills/*/SKILL.md via mkdocs-gen-files (single source of truth stays in skills/).
  • Exit criteria: no content remains that exists only in the README.

Phase 5 — Polish and quality gates

  • Social cards plugin, logo/favicon, 404 page, sitemap.
  • lychee external-link check (weekly cron + PR).
  • Doc-code testing: extract fenced bash/python blocks tagged <!-- test --> and execute them in CI against a temp project so the docs cannot silently rot.
  • Analytics (optional, privacy-respecting) + "Was this page helpful?".
  • Version the site on release tags (mike deploy 0.2 latest).

8. CI/CD

.github/workflows/docs.yml

Trigger Job
pull_request touching docs/**, mkdocs.yml, python/src/** mkdocs build --strict + link check; upload preview artifact
push to main mike deploy --push --update-aliases dev latest
release / tag v* mike deploy --push --update-aliases <tag> latest + mike set-default latest

Cache pip; pin doc deps in the docs extra to keep builds reproducible.

9. Risks and mitigations

Risk Mitigation
Docs drift from the CLI/API Generate CLI + API reference at build time; strict mode fails the build.
Duplicated content between README and site README trimmed to a pointer; CI grep check for duplicated headings (advisory).
Broken links after moving docs/*.md mkdocs-redirects entries + lychee check.
Docstring coverage is currently thin Phase 3 adds pydocstyle to CI incrementally, module by module.
Domain/branding not yet decided Ship on github.io first; CNAME is a one-line change later.

10. Open questions

  1. Domain: buy science-adk.dev, or stay on twmmason.github.io/science-adk?
  2. Is this repo expected to follow Google OSS docs branding, given the "not an officially supported Google product" disclaimer?
  3. Do we version the docs from 0.1.0, or wait until the first PyPI release?
  4. Should tutorials ship as runnable notebooks (adds a Colab dependency)?

11. Estimate

Phase Effort
1 — Scaffold and publish 0.5–1 day
2 — Get Started + Concepts 2–3 days
3 — Generated reference 2 days
4 — Guides, examples, skills 2–3 days
5 — Polish and gates 1–2 days
Total ~8–11 days