From 942b06eeb70a177453f797878e952fe3af0d70b0 Mon Sep 17 00:00:00 2001 From: Adam Page Date: Thu, 1 Oct 2026 08:34:51 -0500 Subject: [PATCH 1/2] docs: make Astro content canonical and retire MkDocs adapter --- .gitignore | 14 +- AGENTS.md | 2 +- HANDOFF.md | 46 +- astro-site/MIGRATION.md | 4 + astro-site/README.md | 6 +- astro-site/package.json | 4 +- .../public}/assets/favicon.png | Bin .../assets/guides/evb-breakout-conn.jpg | Bin .../assets/guides/evb-breakout-conn.webp | Bin .../assets/guides/heartkit-architecture.svg | 0 .../public}/assets/guides/heartkit-demo.png | Bin .../assets/guides/heartkit-rhythm-demo.png | Bin .../assets/guides/max86150-5pin-header.jpg | Bin .../assets/guides/max86150-5pin-header.webp | Bin .../assets/guides/tileio-dashboard.png | Bin .../public}/assets/heartkit-banner.png | Bin .../public}/assets/heartkit-icon-color.png | Bin .../public}/assets/heartkit-logo-dark.png | Bin .../public}/assets/heartkit-logo-light.png | Bin .../public}/assets/logo-white.png | Bin {docs => astro-site/public}/assets/logo.png | Bin .../assets/tasks/beat/beat-example.html | 0 .../assets/tasks/denoise/denoise-example.html | 0 .../diagnostic/diagnostic-pie-visual.png | Bin .../assets/tasks/heartkit-task-diagram.svg | 0 .../assets/tasks/rhythm/rhythm-demo.html | 0 .../assets/tasks/rhythm/rhythm-example.html | 0 .../tasks/segmentation/ecg-annotated.svg | 0 .../tasks/segmentation/segmentation-demo.html | 0 .../segmentation/segmentation-example.html | 0 .../arr-2-eff-sm/confusion_matrix_test.html | 0 .../arr-4-eff-sm/confusion_matrix_test.html | 0 .../beat-2-eff-sm/confusion_matrix_test.html | 0 .../beat-3-eff-sm/confusion_matrix_test.html | 0 .../seg-2-tcn-sm/confusion_matrix_test.html | 0 .../seg-4-tcn-lg/confusion_matrix_test.html | 0 .../seg-4-tcn-sm/confusion_matrix_test.html | 0 .../confusion_matrix_test.html | 0 astro-site/scripts/build-content.mjs | 170 -- astro-site/scripts/build-examples.mjs | 22 + astro-site/scripts/build-notebooks.py | 2 +- astro-site/scripts/build-reference.mjs | 31 +- astro-site/scripts/canonical-content.test.mjs | 21 + astro-site/scripts/check-output.mjs | 23 +- astro-site/scripts/normalize-markdown.mjs | 90 - .../scripts/normalize-markdown.test.mjs | 64 - astro-site/scripts/test-build-notebooks.py | 6 +- .../src/content/docs/datasets/byod.mdx | 11 +- .../src/content/docs/datasets/icentia11k.mdx | 63 +- .../src/content/docs/datasets/index.mdx | 53 + .../src/content/docs/datasets/lsad.mdx | 45 +- astro-site/src/content/docs/datasets/ludb.mdx | 51 + .../src/content/docs/datasets/mitbih.mdx | 42 +- .../src/content/docs/datasets/ptbxl.mdx | 49 +- astro-site/src/content/docs/datasets/qtdb.mdx | 49 + .../src/content/docs/datasets/synthetic.mdx | 42 +- .../src/content/docs/guides/evb-setup.mdx | 19 +- astro-site/src/content/docs/guides/index.mdx | 21 + .../src/content/docs/guides/rhythm-demo.mdx | 37 +- astro-site/src/content/docs/index.mdx | 167 ++ .../src/content/docs/models/byom.mdx | 13 +- .../src/content/docs/models/index.mdx | 15 +- .../src/content/docs/modes/configuration.mdx | 12 +- .../src/content/docs/modes/demo.mdx | 62 +- .../src/content/docs/modes/download.mdx | 15 +- .../src/content/docs/modes/evaluate.mdx | 312 ++++ astro-site/src/content/docs/modes/export.mdx | 312 ++++ astro-site/src/content/docs/modes/index.mdx | 44 + astro-site/src/content/docs/modes/train.mdx | 328 ++++ astro-site/src/content/docs/quickstart.mdx | 258 +++ astro-site/src/content/docs/tasks/beat.mdx | 72 + .../src/content/docs/tasks/byot.mdx | 13 +- .../src/content/docs/tasks/denoise.mdx | 24 +- .../src/content/docs/tasks/diagnostic.mdx | 8 + astro-site/src/content/docs/tasks/index.mdx | 75 + .../src/content/docs/tasks/rhythm.mdx | 80 +- .../src/content/docs/tasks/segmentation.mdx | 105 ++ astro-site/src/content/docs/usage/cli.mdx | 149 ++ astro-site/src/content/docs/usage/python.mdx | 178 ++ .../src/content/docs/zoo/arr-2-eff-sm.mdx | 18 +- .../src/content/docs/zoo/arr-4-eff-sm.mdx | 16 +- .../src/content/docs/zoo/beat-2-eff-sm.mdx | 14 +- .../src/content/docs/zoo/beat-3-eff-sm.mdx | 13 +- .../src/content/docs/zoo/den-ppg-tcn-sm.mdx | 12 +- .../src/content/docs/zoo/den-tcn-lg.mdx | 14 +- .../src/content/docs/zoo/den-tcn-sm.mdx | 15 +- .../src/content/docs/zoo/index.mdx | 21 +- .../src/content/docs/zoo/seg-2-tcn-sm.mdx | 15 +- .../src/content/docs/zoo/seg-4-tcn-lg.mdx | 15 +- .../src/content/docs/zoo/seg-4-tcn-sm.mdx | 15 +- .../src/content/docs/zoo/seg-ppg-2-tcn-sm.mdx | 13 +- astro-site/src/navigation.mjs | 128 +- astro-site/src/redirects.json | 26 + docs/assets/modes/python-demo-snippet.md | 28 - docs/assets/tasks/beat/beat-classes.md | 6 - docs/assets/tasks/rhythm/rhythm-classes.md | 17 - .../segmentation/segmentation-classes.md | 10 - docs/assets/usage/json-configuration.md | 152 -- docs/assets/usage/python-configuration.md | 84 - docs/assets/zoo/arr-2-eff-sm/results.md | 3 - docs/assets/zoo/arr-4-eff-sm/results.md | 3 - docs/assets/zoo/beat-2-eff-sm/results.md | 3 - docs/assets/zoo/beat-3-eff-sm/results.md | 3 - docs/assets/zoo/beat/beat-model-zoo-table.md | 4 - docs/assets/zoo/den-ppg-tcn-sm/results.md | 3 - docs/assets/zoo/den-tcn-lg/results.md | 3 - docs/assets/zoo/den-tcn-sm/results.md | 3 - .../zoo/denoise/denoise-model-zoo-table.md | 5 - docs/assets/zoo/diagnostic/results.md | 2 - .../zoo/rhythm/rhythm-model-zoo-table.md | 4 - docs/assets/zoo/seg-2-tcn-sm/results.md | 3 - docs/assets/zoo/seg-4-tcn-lg/results.md | 3 - docs/assets/zoo/seg-4-tcn-sm/results.md | 3 - docs/assets/zoo/seg-ppg-2-tcn-sm/results.md | 3 - .../segmentation-model-zoo-table.md | 6 - docs/css/custom.css | 213 --- docs/css/mkdocstrings.css | 4 - docs/css/termynal.css | 111 -- docs/datasets/index.md | 52 - docs/datasets/ludb.md | 48 - docs/datasets/qtdb.md | 46 - docs/guides/byot.ipynb | 1069 ----------- docs/guides/ecg-foundation-model.ipynb | 1630 ----------------- docs/guides/index.md | 19 - docs/guides/train-arrhythmia-model.ipynb | 917 ---------- docs/guides/train-ecg-denoiser.ipynb | 1045 ----------- docs/guides/train-ecg-segmentation.ipynb | 1136 ------------ docs/index.md | 159 -- docs/js/custom.js | 144 -- docs/js/termynal.js | 264 --- docs/modes/evaluate.md | 67 - docs/modes/export.md | 66 - docs/modes/index.md | 41 - docs/modes/train.md | 83 - docs/overrides/main.html | 11 - docs/quickstart.md | 155 -- docs/tasks/beat.md | 62 - docs/tasks/diagnostic.md | 5 - docs/tasks/index.md | 77 - docs/tasks/segmentation.md | 90 - docs/usage/cli.md | 144 -- docs/usage/python.md | 87 - mkdocs.yml | 231 --- pyproject.toml | 12 - scripts/gen_ref_pages.py | 36 - uv.lock | 392 +--- 146 files changed, 2860 insertions(+), 9471 deletions(-) rename {docs => astro-site/public}/assets/favicon.png (100%) rename {docs => astro-site/public}/assets/guides/evb-breakout-conn.jpg (100%) rename {docs => astro-site/public}/assets/guides/evb-breakout-conn.webp (100%) rename {docs => astro-site/public}/assets/guides/heartkit-architecture.svg (100%) rename {docs => astro-site/public}/assets/guides/heartkit-demo.png (100%) rename {docs => astro-site/public}/assets/guides/heartkit-rhythm-demo.png (100%) rename {docs => astro-site/public}/assets/guides/max86150-5pin-header.jpg (100%) rename {docs => astro-site/public}/assets/guides/max86150-5pin-header.webp (100%) rename {docs => astro-site/public}/assets/guides/tileio-dashboard.png (100%) rename {docs => astro-site/public}/assets/heartkit-banner.png (100%) rename {docs => astro-site/public}/assets/heartkit-icon-color.png (100%) rename {docs => astro-site/public}/assets/heartkit-logo-dark.png (100%) rename {docs => astro-site/public}/assets/heartkit-logo-light.png (100%) rename {docs => astro-site/public}/assets/logo-white.png (100%) rename {docs => astro-site/public}/assets/logo.png (100%) rename {docs => astro-site/public}/assets/tasks/beat/beat-example.html (100%) rename {docs => astro-site/public}/assets/tasks/denoise/denoise-example.html (100%) rename {docs => astro-site/public}/assets/tasks/diagnostic/diagnostic-pie-visual.png (100%) rename {docs => astro-site/public}/assets/tasks/heartkit-task-diagram.svg (100%) rename {docs => astro-site/public}/assets/tasks/rhythm/rhythm-demo.html (100%) rename {docs => astro-site/public}/assets/tasks/rhythm/rhythm-example.html (100%) rename {docs => astro-site/public}/assets/tasks/segmentation/ecg-annotated.svg (100%) rename {docs => astro-site/public}/assets/tasks/segmentation/segmentation-demo.html (100%) rename {docs => astro-site/public}/assets/tasks/segmentation/segmentation-example.html (100%) rename {docs => astro-site/public}/assets/zoo/arr-2-eff-sm/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/arr-4-eff-sm/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/beat-2-eff-sm/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/beat-3-eff-sm/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/seg-2-tcn-sm/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/seg-4-tcn-lg/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/seg-4-tcn-sm/confusion_matrix_test.html (100%) rename {docs => astro-site/public}/assets/zoo/seg-ppg-2-tcn-sm/confusion_matrix_test.html (100%) delete mode 100644 astro-site/scripts/build-content.mjs create mode 100644 astro-site/scripts/build-examples.mjs create mode 100644 astro-site/scripts/canonical-content.test.mjs delete mode 100644 astro-site/scripts/normalize-markdown.mjs delete mode 100644 astro-site/scripts/normalize-markdown.test.mjs rename docs/datasets/byod.md => astro-site/src/content/docs/datasets/byod.mdx (85%) rename docs/datasets/icentia11k.md => astro-site/src/content/docs/datasets/icentia11k.mdx (50%) create mode 100644 astro-site/src/content/docs/datasets/index.mdx rename docs/datasets/lsad.md => astro-site/src/content/docs/datasets/lsad.mdx (73%) create mode 100644 astro-site/src/content/docs/datasets/ludb.mdx rename docs/datasets/mitbih.md => astro-site/src/content/docs/datasets/mitbih.mdx (51%) rename docs/datasets/ptbxl.md => astro-site/src/content/docs/datasets/ptbxl.mdx (55%) create mode 100644 astro-site/src/content/docs/datasets/qtdb.mdx rename docs/datasets/synthetic.md => astro-site/src/content/docs/datasets/synthetic.mdx (54%) rename docs/guides/evb-setup.md => astro-site/src/content/docs/guides/evb-setup.mdx (65%) create mode 100644 astro-site/src/content/docs/guides/index.mdx rename docs/guides/rhythm-demo.md => astro-site/src/content/docs/guides/rhythm-demo.mdx (68%) create mode 100644 astro-site/src/content/docs/index.mdx rename docs/models/byom.md => astro-site/src/content/docs/models/byom.mdx (87%) rename docs/models/index.md => astro-site/src/content/docs/models/index.mdx (90%) rename docs/modes/configuration.md => astro-site/src/content/docs/modes/configuration.mdx (91%) rename docs/modes/demo.md => astro-site/src/content/docs/modes/demo.mdx (76%) rename docs/modes/download.md => astro-site/src/content/docs/modes/download.mdx (57%) create mode 100644 astro-site/src/content/docs/modes/evaluate.mdx create mode 100644 astro-site/src/content/docs/modes/export.mdx create mode 100644 astro-site/src/content/docs/modes/index.mdx create mode 100644 astro-site/src/content/docs/modes/train.mdx create mode 100644 astro-site/src/content/docs/quickstart.mdx create mode 100644 astro-site/src/content/docs/tasks/beat.mdx rename docs/tasks/byot.md => astro-site/src/content/docs/tasks/byot.mdx (77%) rename docs/tasks/denoise.md => astro-site/src/content/docs/tasks/denoise.mdx (64%) create mode 100644 astro-site/src/content/docs/tasks/diagnostic.mdx create mode 100644 astro-site/src/content/docs/tasks/index.mdx rename docs/tasks/rhythm.md => astro-site/src/content/docs/tasks/rhythm.mdx (56%) create mode 100644 astro-site/src/content/docs/tasks/segmentation.mdx create mode 100644 astro-site/src/content/docs/usage/cli.mdx create mode 100644 astro-site/src/content/docs/usage/python.mdx rename docs/zoo/arr-2-eff-sm.md => astro-site/src/content/docs/zoo/arr-2-eff-sm.mdx (67%) rename docs/zoo/arr-4-eff-sm.md => astro-site/src/content/docs/zoo/arr-4-eff-sm.mdx (69%) rename docs/zoo/beat-2-eff-sm.md => astro-site/src/content/docs/zoo/beat-2-eff-sm.mdx (69%) rename docs/zoo/beat-3-eff-sm.md => astro-site/src/content/docs/zoo/beat-3-eff-sm.mdx (71%) rename docs/zoo/den-ppg-tcn-sm.md => astro-site/src/content/docs/zoo/den-ppg-tcn-sm.mdx (71%) rename docs/zoo/den-tcn-lg.md => astro-site/src/content/docs/zoo/den-tcn-lg.mdx (70%) rename docs/zoo/den-tcn-sm.md => astro-site/src/content/docs/zoo/den-tcn-sm.mdx (70%) rename docs/zoo/index.md => astro-site/src/content/docs/zoo/index.mdx (87%) rename docs/zoo/seg-2-tcn-sm.md => astro-site/src/content/docs/zoo/seg-2-tcn-sm.mdx (69%) rename docs/zoo/seg-4-tcn-lg.md => astro-site/src/content/docs/zoo/seg-4-tcn-lg.mdx (70%) rename docs/zoo/seg-4-tcn-sm.md => astro-site/src/content/docs/zoo/seg-4-tcn-sm.mdx (69%) rename docs/zoo/seg-ppg-2-tcn-sm.md => astro-site/src/content/docs/zoo/seg-ppg-2-tcn-sm.mdx (68%) create mode 100644 astro-site/src/redirects.json delete mode 100644 docs/assets/modes/python-demo-snippet.md delete mode 100644 docs/assets/tasks/beat/beat-classes.md delete mode 100644 docs/assets/tasks/rhythm/rhythm-classes.md delete mode 100644 docs/assets/tasks/segmentation/segmentation-classes.md delete mode 100644 docs/assets/usage/json-configuration.md delete mode 100644 docs/assets/usage/python-configuration.md delete mode 100644 docs/assets/zoo/arr-2-eff-sm/results.md delete mode 100644 docs/assets/zoo/arr-4-eff-sm/results.md delete mode 100644 docs/assets/zoo/beat-2-eff-sm/results.md delete mode 100644 docs/assets/zoo/beat-3-eff-sm/results.md delete mode 100644 docs/assets/zoo/beat/beat-model-zoo-table.md delete mode 100644 docs/assets/zoo/den-ppg-tcn-sm/results.md delete mode 100644 docs/assets/zoo/den-tcn-lg/results.md delete mode 100644 docs/assets/zoo/den-tcn-sm/results.md delete mode 100644 docs/assets/zoo/denoise/denoise-model-zoo-table.md delete mode 100644 docs/assets/zoo/diagnostic/results.md delete mode 100644 docs/assets/zoo/rhythm/rhythm-model-zoo-table.md delete mode 100644 docs/assets/zoo/seg-2-tcn-sm/results.md delete mode 100644 docs/assets/zoo/seg-4-tcn-lg/results.md delete mode 100644 docs/assets/zoo/seg-4-tcn-sm/results.md delete mode 100644 docs/assets/zoo/seg-ppg-2-tcn-sm/results.md delete mode 100644 docs/assets/zoo/segmentation/segmentation-model-zoo-table.md delete mode 100644 docs/css/custom.css delete mode 100644 docs/css/mkdocstrings.css delete mode 100644 docs/css/termynal.css delete mode 100644 docs/datasets/index.md delete mode 100644 docs/datasets/ludb.md delete mode 100644 docs/datasets/qtdb.md delete mode 100644 docs/guides/byot.ipynb delete mode 100644 docs/guides/ecg-foundation-model.ipynb delete mode 100644 docs/guides/index.md delete mode 100644 docs/guides/train-arrhythmia-model.ipynb delete mode 100644 docs/guides/train-ecg-denoiser.ipynb delete mode 100644 docs/guides/train-ecg-segmentation.ipynb delete mode 100644 docs/index.md delete mode 100644 docs/js/custom.js delete mode 100644 docs/js/termynal.js delete mode 100644 docs/modes/evaluate.md delete mode 100644 docs/modes/export.md delete mode 100644 docs/modes/index.md delete mode 100644 docs/modes/train.md delete mode 100644 docs/overrides/main.html delete mode 100644 docs/quickstart.md delete mode 100644 docs/tasks/beat.md delete mode 100644 docs/tasks/diagnostic.md delete mode 100644 docs/tasks/index.md delete mode 100644 docs/tasks/segmentation.md delete mode 100644 docs/usage/cli.md delete mode 100644 docs/usage/python.md delete mode 100644 mkdocs.yml delete mode 100644 scripts/gen_ref_pages.py diff --git a/.gitignore b/.gitignore index 17dd0e82..a6e3e8a5 100644 --- a/.gitignore +++ b/.gitignore @@ -159,8 +159,6 @@ venv.bak/ # Rope project settings .ropeproject -# mkdocs documentation -/site # mypy .mypy_cache/ @@ -186,8 +184,16 @@ cython_debug/ astro-site/node_modules/ astro-site/.astro/ -astro-site/src/content/docs/ astro-site/src/data/ -astro-site/public/ astro-site/test-results/ astro-site/playwright-report/ + +astro-site/src/content/docs/reference/ +astro-site/public/reference/ +astro-site/public/notebooks/ +astro-site/public/examples/ +astro-site/src/content/docs/guides/byot.md +astro-site/src/content/docs/guides/train-ecg-segmentation.md +astro-site/src/content/docs/guides/train-arrhythmia-model.md +astro-site/src/content/docs/guides/ecg-foundation-model.md +astro-site/src/content/docs/guides/train-ecg-denoiser.md diff --git a/AGENTS.md b/AGENTS.md index 5417f79b..99aef84e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -2,7 +2,7 @@ Repo-specific notes for automation and maintenance: - Python target is 3.12; use `uv sync` for installs and `uv run pytest tests/` for tests. -- Docs use Astro/Starlight in `astro-site/`, generated from Markdown under `docs/`, saved notebooks and Python docstrings. Edit sources rather than generated content. +- Docs use Astro/Starlight in `astro-site/`, with authored Markdown/MDX in `astro-site/src/content/docs/` and navigation in `astro-site/src/navigation.mjs`. Only notebook guides and Python API pages are generated; edit their sources. - Use Node 24. From `astro-site/`, run `npm ci`, `npm run check`, `npm run build`, `npm run check:output` and `npm test`. Builds need Python and uv for static API extraction; notebook training is not executed. - The documentation workflow deploys Pages from main independently of package releases. Preserve historical URL redirects and keep headings plain Markdown. - Prefer `rg` for searches and avoid touching binary assets unless requested. diff --git a/HANDOFF.md b/HANDOFF.md index 7d36ead3..15b01a75 100644 --- a/HANDOFF.md +++ b/HANDOFF.md @@ -1,45 +1,13 @@ -# heartKIT Astro migration +# Canonical Astro documentation -## Goal and scope +Issue: AmbiqAI/heartkit#47. Branch: codex/canonical-astro-docs. -Migrate public docs to Astro/Starlight using the sleepKIT layout and conversion fixes. Preserve content and URLs, render saved notebook outputs, generate public Python reference, and deploy docs independently of package releases. Runtime updates, model refreshes and Hugging Face deployment are separate follow-ups. +Goal: retire the MkDocs compatibility layer without changing published content or runtime behavior. -## References +Baseline build passed. Source and output baselines are saved under /tmp/heartkit-canonical-baseline. Worktree is isolated from prior migration work. -- Issue: https://github.com/AmbiqAI/heartkit/issues/43 (creation approved). -- Worktree: /Users/adam.page/Ambiq/adks/heartkit-docs -- Branch: codex/heartkit-astro; baseline 64cd51b, version 1.8.0. -- Preview: http://127.0.0.1:8777/heartkit/ -- Primary checkout untouched. PR: https://github.com/AmbiqAI/heartkit/pull/44 (250c9e7). Both independent reviews complete; findings resolved. Python CI and documentation CI passed on 250c9e7; heartKIT merge remains for user approval. +Plan: keep authored MDX and navigation; retain API/notebook generation; remove unused MkDocs config/dependencies; verify content, links, downloads and browser behavior. Publish PR for review; do not merge without approval. -## Implemented +Implementation: authored MDX and static public assets are tracked; navigation is direct Astro configuration; static redirects are checked in. API, notebook and example-download generation remain. Removed MkDocs config, converters, duplicate notebook sources and docs dependency group; lock regenerated. sleepKIT retains golden-contract evidence at docs/evidence and private notes in docs-maintainers. -Astro site under astro-site, scoped navigation, branded dark hero and independent Pages workflow. Preserved MkDocs sources and repaired malformed syntax, missing model-zoo snippet includes and docstring formatting. Python edits affect docstrings only. - -Migrated 44 standalone Markdown pages, five notebooks and 122 public API modules (161 catalog symbols). All five docs/notebooks pairs are identical. Downloads preserve original bytes; all 18 saved PNG figures render. Notebooks were not executed. Rich HTML outputs use plain-text fallbacks. Private modules are excluded from API pages and exports. Historical API and notebook URLs redirect. - -## Verified - -Production build and internal links across 334 HTML documents pass. Astro check: zero errors, warnings or hints. Four converter tests and seven browser tests pass. All 49 authored/notebook routes loaded at desktop and mobile widths without horizontal overflow or broken images; selected landing, Quickstart and notebook screenshots inspected. All 32 copied non-theme assets are byte-identical. git diff --check and notebook-renderer Ruff checks pass. - -## Follow-up refinements - -Restored the shared heliaEDGE/heartKIT red token mapping and a brighter red hero accent. Added uvx/pipx installation tabs with reduced-motion-aware transitions, replaced task recap tabs with a comparison table, and removed obsolete code annotation markers. Missing snippet includes now fail the build instead of silently emitting placeholder content. Desktop/mobile hero and installation screenshots inspected; installation tabs exercised. Retained interactive ECG traces and confusion matrices. - -Hero copy approved: “Turn heart signals into on-device intelligence.” Introduction describes heartKIT as a Python-based AI Development Kit for heart monitoring on Ambiq devices. - -Latest browser feedback resolved: mobile section switcher with only active-section pages, clearer workflow labels and no duplicate modes entry, compact footer pagination and explicit source link. Workflow recap is a comparison table; rhythm descriptions use headings. Shared configuration snippet was mislabeled JavaScript; now validated JSON with collapsed preview/download everywhere included. Train/evaluate/export diagrams use readable vertical flows. Added browser regressions for mobile section switching and configuration expansion/downloads. - -Published-site audit: all 190 original sitemap routes now resolve; added 19 missing legacy redirects (API summary and standalone snippets). Checked 50 authored content tables and 348 public API names with no missing content. Original assets page was also empty; docstrings now explain bundled noise resources. Legacy route fixture guards URL coverage. See MIGRATION.md for evidence and review limits. - -## Review and release status - -Two independent content and delivery reviews completed. Fixed BYOT introduction loss from badge-cell skipping and preserved query/fragment on legacy redirects. Added two notebook regression tests and an eighth browser test. Delivery reviewer rechecked redirect security and JavaScript-disabled fallback; no remaining findings. Python behavior is unchanged; Ruff 0.11.12 passed. - -Shared UI #185 and release PR #186 are merged. Publication workflow 36793695398 passed; v0.1.0-alpha.22 points to a62e8d45505dd3bbcdf1c4a03dfd1ec863322ecf. heartKIT package.json and regenerated lockfile pin that exact released commit. This replaces the temporary local preview package. Compact terminals within tabs retain copy controls without redundant headers. - -Clean npm ci, Astro check, build, output checks and all eight browser tests pass on alpha.22. Rendered installation panel inspected; screenshot /tmp/heartkit-alpha22-terminal.png. CI on the dependency update is the remaining qualification step before final user merge approval. - -## Next steps and limits - -Push the dependency update and verify GitHub CI, then request final owner approval for heartKIT #44. Do not merge heartKIT without approval. Keep package release workflows unchanged. Other product consistency PRs follow heartKIT landing. Runtime updates, model refreshes and Hugging Face deployment are separate follow-ups. External links, runtime examples, dataset access, historical metrics and training were not revalidated. See astro-site/MIGRATION.md and README.md for coverage and commands. +Verified: baseline and migrated route sets identical; all static assets, notebook downloads and example downloads byte-identical; authored MDX unchanged. Build/type/output checks passed, including generation-preserves-authored-source regression. Browser suites passed (heartKIT 8, sleepKIT 17). Clean install with generated outputs removed, build/type/output checks and visual review passed. No third-party lockfile package versions changed. heartKIT lock regeneration also aligns its project version with pyproject.toml. PR publication pending. EDGE cleanup is already landed. AOT MkDocs is an active exported-model offline-doc feature, intentionally retained. diff --git a/astro-site/MIGRATION.md b/astro-site/MIGRATION.md index 3ff7bdd2..4d76d00e 100644 --- a/astro-site/MIGRATION.md +++ b/astro-site/MIGRATION.md @@ -33,3 +33,7 @@ Inspected original-site screenshots for the homepage, assets API, guide index an Content review identified two migration regressions: removing a Colab toolbar discarded BYOT prose in the same cell, and static redirects discarded API symbol fragments. The renderer now removes only toolbar markup; redirects preserve query strings and fragments with a meta-refresh fallback when JavaScript is disabled. Both changes have regression coverage. Delivery review checked Pages permissions and triggers, shared section matching, notebook assets, public API coverage and Python AST parity. No additional blocking findings remained after fix review. Dependency qualification: shared UI alpha.21 is pinned by immutable commit `6cdbea0c594c955e6aeef232af1fbb15e395ab2d` (AmbiqAI/helia-ui#183 and #184). Clean installation, type checks, build, output checks and all eight browser tests pass with this dependency. + +## Canonical sources + +The one-time MkDocs adapter has been retired. Authored pages are now in `src/content/docs/`, navigation in `src/navigation.mjs`, and static assets in `public/`. API and notebook generation remain. See README.md for source ownership. diff --git a/astro-site/README.md b/astro-site/README.md index 70855d25..24e24cfe 100644 --- a/astro-site/README.md +++ b/astro-site/README.md @@ -14,8 +14,10 @@ npm run check:output npm test ``` -Edit source Markdown, notebook sources or owning scripts. `src/content/docs`, `src/data`, `public`, `.cache` and `dist` are generated. Existing navigation labels come from `mkdocs.yml`; `src/navigation.mjs` assigns public pages to five scoped sections. +Edit authored Markdown/MDX in `src/content/docs/`, navigation in `src/navigation.mjs`, static redirects in `src/redirects.json`, and static assets in `public/`. These are canonical sources and are never replaced by the build. -The five notebook pairs in `docs/guides` and `notebooks` were identical at migration. Documentation copies supply the rendered pages and byte-identical downloads. Saved outputs include 18 PNG figures, logs and plain-text fallbacks for rich HTML. No notebook execution occurs during builds. Notebook timestamps and measurements are historical, not current model qualification. +`prepare:docs` generates only downloadable configuration examples, notebook guides/assets, and Python API pages/data. API output under `src/content/docs/reference/`, notebook `.md` pages under `guides/`, `src/data/`, and `public/{reference,notebooks,examples}/` are ignored. Edit Python docstrings or the notebooks in `../notebooks/` for those outputs. There is no MkDocs configuration or Markdown conversion step. + +The five notebooks in `notebooks/` supply rendered pages and byte-identical downloads. Duplicate documentation copies have been removed. Saved outputs include 18 PNG figures, logs and plain-text fallbacks for rich HTML. No notebook execution occurs during builds. Notebook timestamps and measurements are historical, not current model qualification. PRs build and test the site. Main pushes and manual main dispatches publish Pages independently of package releases. Package release workflows are unchanged. diff --git a/astro-site/package.json b/astro-site/package.json index c857df49..9f0c5019 100644 --- a/astro-site/package.json +++ b/astro-site/package.json @@ -9,7 +9,7 @@ "npm": ">=11" }, "scripts": { - "prepare:docs": "node scripts/build-content.mjs && python3 scripts/build-notebooks.py && node scripts/build-reference.mjs", + "prepare:docs": "node scripts/build-examples.mjs && python3 scripts/build-notebooks.py && node scripts/build-reference.mjs", "predev": "npm run prepare:docs", "dev": "astro dev", "prebuild": "npm run prepare:docs", @@ -17,7 +17,7 @@ "postbuild": "node scripts/publish-reference.mjs", "precheck": "npm run prepare:docs", "check": "astro check", - "check:output": "python3 scripts/test-build-notebooks.py && node --test scripts/normalize-markdown.test.mjs && node scripts/check-output.mjs", + "check:output": "node --test scripts/canonical-content.test.mjs && python3 scripts/test-build-notebooks.py && node scripts/check-output.mjs", "test": "playwright test" }, "dependencies": { diff --git a/docs/assets/favicon.png b/astro-site/public/assets/favicon.png similarity index 100% rename from docs/assets/favicon.png rename to astro-site/public/assets/favicon.png diff --git a/docs/assets/guides/evb-breakout-conn.jpg b/astro-site/public/assets/guides/evb-breakout-conn.jpg similarity index 100% rename from docs/assets/guides/evb-breakout-conn.jpg rename to astro-site/public/assets/guides/evb-breakout-conn.jpg diff --git a/docs/assets/guides/evb-breakout-conn.webp b/astro-site/public/assets/guides/evb-breakout-conn.webp similarity index 100% rename from docs/assets/guides/evb-breakout-conn.webp rename to astro-site/public/assets/guides/evb-breakout-conn.webp diff --git a/docs/assets/guides/heartkit-architecture.svg b/astro-site/public/assets/guides/heartkit-architecture.svg similarity index 100% rename from docs/assets/guides/heartkit-architecture.svg rename to astro-site/public/assets/guides/heartkit-architecture.svg diff --git a/docs/assets/guides/heartkit-demo.png b/astro-site/public/assets/guides/heartkit-demo.png similarity index 100% rename from docs/assets/guides/heartkit-demo.png rename to astro-site/public/assets/guides/heartkit-demo.png diff --git a/docs/assets/guides/heartkit-rhythm-demo.png b/astro-site/public/assets/guides/heartkit-rhythm-demo.png similarity index 100% rename from docs/assets/guides/heartkit-rhythm-demo.png rename to astro-site/public/assets/guides/heartkit-rhythm-demo.png diff --git a/docs/assets/guides/max86150-5pin-header.jpg b/astro-site/public/assets/guides/max86150-5pin-header.jpg similarity index 100% rename from docs/assets/guides/max86150-5pin-header.jpg rename to astro-site/public/assets/guides/max86150-5pin-header.jpg diff --git a/docs/assets/guides/max86150-5pin-header.webp b/astro-site/public/assets/guides/max86150-5pin-header.webp similarity index 100% rename from docs/assets/guides/max86150-5pin-header.webp rename to astro-site/public/assets/guides/max86150-5pin-header.webp diff --git a/docs/assets/guides/tileio-dashboard.png b/astro-site/public/assets/guides/tileio-dashboard.png similarity index 100% rename from docs/assets/guides/tileio-dashboard.png rename to astro-site/public/assets/guides/tileio-dashboard.png diff --git a/docs/assets/heartkit-banner.png b/astro-site/public/assets/heartkit-banner.png similarity index 100% rename from docs/assets/heartkit-banner.png rename to astro-site/public/assets/heartkit-banner.png diff --git a/docs/assets/heartkit-icon-color.png b/astro-site/public/assets/heartkit-icon-color.png similarity index 100% rename from docs/assets/heartkit-icon-color.png rename to astro-site/public/assets/heartkit-icon-color.png diff --git a/docs/assets/heartkit-logo-dark.png b/astro-site/public/assets/heartkit-logo-dark.png similarity index 100% rename from docs/assets/heartkit-logo-dark.png rename to astro-site/public/assets/heartkit-logo-dark.png diff --git a/docs/assets/heartkit-logo-light.png b/astro-site/public/assets/heartkit-logo-light.png similarity index 100% rename from docs/assets/heartkit-logo-light.png rename to astro-site/public/assets/heartkit-logo-light.png diff --git a/docs/assets/logo-white.png b/astro-site/public/assets/logo-white.png similarity index 100% rename from docs/assets/logo-white.png rename to astro-site/public/assets/logo-white.png diff --git a/docs/assets/logo.png b/astro-site/public/assets/logo.png similarity index 100% rename from docs/assets/logo.png rename to astro-site/public/assets/logo.png diff --git a/docs/assets/tasks/beat/beat-example.html b/astro-site/public/assets/tasks/beat/beat-example.html similarity index 100% rename from docs/assets/tasks/beat/beat-example.html rename to astro-site/public/assets/tasks/beat/beat-example.html diff --git a/docs/assets/tasks/denoise/denoise-example.html b/astro-site/public/assets/tasks/denoise/denoise-example.html similarity index 100% rename from docs/assets/tasks/denoise/denoise-example.html rename to astro-site/public/assets/tasks/denoise/denoise-example.html diff --git a/docs/assets/tasks/diagnostic/diagnostic-pie-visual.png b/astro-site/public/assets/tasks/diagnostic/diagnostic-pie-visual.png similarity index 100% rename from docs/assets/tasks/diagnostic/diagnostic-pie-visual.png rename to astro-site/public/assets/tasks/diagnostic/diagnostic-pie-visual.png diff --git a/docs/assets/tasks/heartkit-task-diagram.svg b/astro-site/public/assets/tasks/heartkit-task-diagram.svg similarity index 100% rename from docs/assets/tasks/heartkit-task-diagram.svg rename to astro-site/public/assets/tasks/heartkit-task-diagram.svg diff --git a/docs/assets/tasks/rhythm/rhythm-demo.html b/astro-site/public/assets/tasks/rhythm/rhythm-demo.html similarity index 100% rename from docs/assets/tasks/rhythm/rhythm-demo.html rename to astro-site/public/assets/tasks/rhythm/rhythm-demo.html diff --git a/docs/assets/tasks/rhythm/rhythm-example.html b/astro-site/public/assets/tasks/rhythm/rhythm-example.html similarity index 100% rename from docs/assets/tasks/rhythm/rhythm-example.html rename to astro-site/public/assets/tasks/rhythm/rhythm-example.html diff --git a/docs/assets/tasks/segmentation/ecg-annotated.svg b/astro-site/public/assets/tasks/segmentation/ecg-annotated.svg similarity index 100% rename from docs/assets/tasks/segmentation/ecg-annotated.svg rename to astro-site/public/assets/tasks/segmentation/ecg-annotated.svg diff --git a/docs/assets/tasks/segmentation/segmentation-demo.html b/astro-site/public/assets/tasks/segmentation/segmentation-demo.html similarity index 100% rename from docs/assets/tasks/segmentation/segmentation-demo.html rename to astro-site/public/assets/tasks/segmentation/segmentation-demo.html diff --git a/docs/assets/tasks/segmentation/segmentation-example.html b/astro-site/public/assets/tasks/segmentation/segmentation-example.html similarity index 100% rename from docs/assets/tasks/segmentation/segmentation-example.html rename to astro-site/public/assets/tasks/segmentation/segmentation-example.html diff --git a/docs/assets/zoo/arr-2-eff-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/arr-2-eff-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/arr-2-eff-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/arr-2-eff-sm/confusion_matrix_test.html diff --git a/docs/assets/zoo/arr-4-eff-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/arr-4-eff-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/arr-4-eff-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/arr-4-eff-sm/confusion_matrix_test.html diff --git a/docs/assets/zoo/beat-2-eff-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/beat-2-eff-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/beat-2-eff-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/beat-2-eff-sm/confusion_matrix_test.html diff --git a/docs/assets/zoo/beat-3-eff-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/beat-3-eff-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/beat-3-eff-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/beat-3-eff-sm/confusion_matrix_test.html diff --git a/docs/assets/zoo/seg-2-tcn-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/seg-2-tcn-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/seg-2-tcn-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/seg-2-tcn-sm/confusion_matrix_test.html diff --git a/docs/assets/zoo/seg-4-tcn-lg/confusion_matrix_test.html b/astro-site/public/assets/zoo/seg-4-tcn-lg/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/seg-4-tcn-lg/confusion_matrix_test.html rename to astro-site/public/assets/zoo/seg-4-tcn-lg/confusion_matrix_test.html diff --git a/docs/assets/zoo/seg-4-tcn-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/seg-4-tcn-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/seg-4-tcn-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/seg-4-tcn-sm/confusion_matrix_test.html diff --git a/docs/assets/zoo/seg-ppg-2-tcn-sm/confusion_matrix_test.html b/astro-site/public/assets/zoo/seg-ppg-2-tcn-sm/confusion_matrix_test.html similarity index 100% rename from docs/assets/zoo/seg-ppg-2-tcn-sm/confusion_matrix_test.html rename to astro-site/public/assets/zoo/seg-ppg-2-tcn-sm/confusion_matrix_test.html diff --git a/astro-site/scripts/build-content.mjs b/astro-site/scripts/build-content.mjs deleted file mode 100644 index b6e99492..00000000 --- a/astro-site/scripts/build-content.mjs +++ /dev/null @@ -1,170 +0,0 @@ -import { internalPages } from "./public-docs.mjs"; -import { - existsSync, - readFileSync, - writeFileSync, - mkdirSync, - readdirSync, - cpSync, - rmSync, -} from "node:fs"; -import { dirname, resolve, relative } from "node:path"; -import { - convertPage, - createState, - parseNav, - buildSidebar, -} from "../node_modules/@ambiqai/helia-ui/scripts/lib/mkdocs-convert-render.mjs"; -import { normalizeMarkdown, expandSnippets } from "./normalize-markdown.mjs"; -const source = resolve("../docs"); -const out = resolve("src/content/docs"); -const walk = (dir) => - readdirSync(dir, { withFileTypes: true }).flatMap((e) => - e.isDirectory() ? walk(resolve(dir, e.name)) : [resolve(dir, e.name)], - ); -const state = createState(); -const titles = {}; -rmSync(out, { recursive: true, force: true }); -mkdirSync(out, { recursive: true }); -rmSync("public/examples", { recursive: true, force: true }); -mkdirSync("src/data", { recursive: true }); -function readSnippet(file) { - const path = resolve(source, file); - if (!path.startsWith(source + "/")) - throw Error(`Snippet outside docs: ${file}`); - if (!existsSync(path)) throw Error(`Missing snippet: ${file}`); - if (file.endsWith(".html")) - return `