Skip to content

docs: make Astro content canonical and retire MkDocs adapter - #49

Merged
apage224 merged 2 commits into
mainfrom
codex/canonical-astro-docs
Oct 1, 2026
Merged

apage224 merged 2 commits into
mainfrom
codex/canonical-astro-docs

Conversation

@apage224

@apage224 apage224 commented Oct 1, 2026 •

Copy link
Copy Markdown
Collaborator

The Astro build still treated MkDocs Markdown and navigation as migration inputs, overwriting authored pages on every build. This makes the existing migrated pages, navigation and static assets canonical, and removes the adapter, MkDocs configuration and unused docs dependencies.

API pages, notebook guides and downloadable examples remain generated. Public routes, redirects and downloaded assets are preserved. Private notes move to docs-maintainers; golden-contract evidence retains its stable docs/evidence path and is copied into the site. The distinct previous notebook remains an explicit archive.

Validation:

  • Clean npm install, build, type checks, output/link checks and locked dependency verification passed.
  • Generation-preserves-authored-content regression passed.
  • 17 browser tests passed; mobile light and desktop dark rendering inspected.
  • Baseline comparison found identical HTML route sets and byte-identical assets and configuration downloads. Notebook source/Colab links are intentionally corrected to the canonical paths; saved outputs are preserved.
  • Python documentation-script lint passed. No ML training or hardware tests were run locally; normal repository CI remains required.

No runtime/model behavior changes. CompressionKIT migration remains deferred until this cleanup lands. AOT retains MkDocs for its active exported-model offline documentation feature; EDGE cleanup is separate.

Closes #48

Copilot AI balanced review requested due to automatic review settings October 1, 2026 13:34

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🟡 Changes recommended

Clean output validation, a documented download command, and notebook source links currently have concrete regressions.

Review effort: Balanced
Findings: 1 High severity · 1 Medium severity · 2 Low severity

Open (4)
What changed in this PR

Makes Astro the canonical documentation source while retiring the MkDocs compatibility layer.

Changes:

  • Moves authored content, navigation, redirects, and assets to Astro.
  • Retains targeted API, notebook, example, and evidence generation.
  • Removes obsolete MkDocs sources, tooling, configuration, and dependencies.
File Description
scripts/​gen_ref_pages.py Removes MkDocs API generation.
README.md Updates documentation links.
pyproject.toml Removes MkDocs dependencies.
mkdocs.yml Removes retired MkDocs configuration.
HANDOFF.md Adds migration handoff notes.
docs/​zoo/​index.md Removes duplicate MkDocs page.
docs/​zoo/​detect.md Removes duplicate detection-model page.
docs/​zoo/​apnea.md Removes duplicate apnea-model page.
docs/​usage/​python.md Removes duplicate Python guide.
docs/​usage/​cli.md Removes duplicate CLI guide.
docs/​tasks/​stage.md Removes duplicate staging page.
docs/​tasks/​detect.md Removes duplicate detection page.
docs/​tasks/​arousal.md Removes duplicate arousal placeholder.
docs/​tasks/​apnea.md Removes duplicate apnea page.
docs/​quickstart.md Removes duplicate quickstart.
docs/​modes/​train.md Removes duplicate training guide.
docs/​modes/​export.md Removes duplicate export guide.
docs/​modes/​evaluate.md Removes duplicate evaluation guide.
docs/​modes/​download.md Removes duplicate download guide.
docs/​js/​termynal.js Removes MkDocs terminal script.
docs/​js/​custom.js Removes MkDocs custom script.
docs/​guides/​index.md Removes duplicate guide index.
docs/​features/​index.md Removes duplicate feature index.
docs/​datasets/​index.md Removes duplicate dataset index.
docs/​css/​termynal.css Removes MkDocs terminal styling.
docs/​css/​mkdocstrings.css Removes MkDocstrings styling.
docs/​css/​custom.css Removes MkDocs-specific styling.
docs/​assets/​zoo/​stage/​stage-model-zoo-table.md Removes embedded MkDocs snippet.
docs/​assets/​zoo/​stage/​stage-model-hw-table.md Removes staging hardware snippet.
docs/​assets/​zoo/​detect/​sleep-detect-2-config.md Removes obsolete configuration snippet.
docs/​assets/​zoo/​detect/​detect-model-zoo-table.md Removes detection table snippet.
docs/​assets/​zoo/​detect/​detect-model-hw-table.md Removes detection hardware snippet.
docs/​assets/​zoo/​apnea/​apnea-model-zoo-table.md Removes apnea table snippet.
docs/​assets/​zoo/​apnea/​apnea-model-hw-table.md Removes apnea hardware snippet.
docs/​assets/​usage/​python-configuration.md Removes Python configuration snippet.
docs/​assets/​usage/​json-configuration.md Removes JSON configuration snippet.
docs/​assets/​tasks/​stage/​stage-default-class-table.md Removes staging-class snippet.
docs/​assets/​tasks/​detect/​detect-default-class-table.md Removes detection-class snippet.
docs/​assets/​tasks/​apnea/​apnea-classes.md Removes apnea-class snippet.
docs-maintainers/​shared-foundation.md Updates links to canonical Astro pages.
docs-maintainers/​reusable-blocks.md Moves reusable-component notes private.
docs-maintainers/​licenses/​ambiq-device-model-license-draft.md Updates licensing-policy link.
docs-maintainers/​detection-preparation-performance.md Updates public-page and evidence links.
astro-site/​src/​redirects.json Adds canonical static redirect source.
astro-site/​src/​navigation.mjs Inlines canonical navigation entries.
astro-site/​src/​content/​docs/​zoo/​index.mdx Adds canonical model-zoo index.
astro-site/​src/​content/​docs/​zoo/​detect.mdx Adds canonical detection-model page.
astro-site/​src/​content/​docs/​zoo/​apnea.mdx Adds canonical apnea-model page.
astro-site/​src/​content/​docs/​usage/​cli.mdx Adds canonical CLI guide.
astro-site/​src/​content/​docs/​tasks/​index.mdx Converts task index to canonical MDX.
astro-site/​src/​content/​docs/​tasks/​detect.mdx Adds canonical detection task page.
astro-site/​src/​content/​docs/​tasks/​byot.mdx Converts custom-task guide.
astro-site/​src/​content/​docs/​tasks/​arousal.mdx Adds canonical compatibility page.
astro-site/​src/​content/​docs/​tasks/​apnea.mdx Adds canonical apnea task page.
astro-site/​src/​content/​docs/​staging-training.mdx Converts staging-training guide.
astro-site/​src/​content/​docs/​staging-baseline.mdx Converts staging baseline guide.
astro-site/​src/​content/​docs/​modes/​index.mdx Converts mode overview.
astro-site/​src/​content/​docs/​modes/​download.mdx Adds canonical download guide.
astro-site/​src/​content/​docs/​modes/​demo.mdx Converts demo guide and embeds output.
astro-site/​src/​content/​docs/​modes/​configuration.mdx Converts configuration reference.
astro-site/​src/​content/​docs/​models/​index.mdx Converts model index.
astro-site/​src/​content/​docs/​models/​byom.mdx Converts custom-model guide.
astro-site/​src/​content/​docs/​model-licensing-policy.mdx Converts licensing policy.
astro-site/​src/​content/​docs/​huggingface-artifacts.mdx Converts artifact publishing guide.
astro-site/​src/​content/​docs/​guides/​stage-ablation.mdx Converts ablation guide and plots.
astro-site/​src/​content/​docs/​guides/​index.mdx Adds canonical guide index.
astro-site/​src/​content/​docs/​features/​fs_w_pa_14.mdx Converts FS-W-PA-14 reference.
astro-site/​src/​content/​docs/​features/​fs_w_p_5.mdx Converts FS-W-P-5 reference.
astro-site/​src/​content/​docs/​features/​fs_w_a_5.mdx Converts FS-W-A-5 reference.
astro-site/​src/​content/​docs/​features/​fs_h_e_10.mdx Converts FS-H-E-10 reference.
astro-site/​src/​content/​docs/​features/​fs_c_ear_9.mdx Converts FS-C-EAR-9 reference.
astro-site/​src/​content/​docs/​features/​byofs.mdx Converts custom-feature guide.
astro-site/​src/​content/​docs/​detection-source-alignment.mdx Converts alignment guide.
astro-site/​src/​content/​docs/​detection-sample-clock.mdx Converts sample-clock guide.
astro-site/​src/​content/​docs/​detection-recipe.mdx Converts detection recipe.
astro-site/​src/​content/​docs/​detection-profiling.mdx Converts profiling guide.
astro-site/​src/​content/​docs/​detection-label-policy.mdx Converts label-policy record.
astro-site/​src/​content/​docs/​detection-int8.mdx Converts INT8 guide.
astro-site/​src/​content/​docs/​detection-golden.mdx Converts golden-baseline guide.
astro-site/​src/​content/​docs/​detection-frozen-split.mdx Converts split documentation.
astro-site/​src/​content/​docs/​detection-first-experiment.mdx Converts experiment report.
astro-site/​src/​content/​docs/​detection-evaluation-protocol.mdx Converts evaluation protocol.
astro-site/​src/​content/​docs/​detection-comparison.mdx Converts comparison report.
astro-site/​src/​content/​docs/​detection-annotated-dataset.mdx Converts annotated-dataset guide.
astro-site/​src/​content/​docs/​datasets/​ysyw.mdx Converts YSYW page.
astro-site/​src/​content/​docs/​datasets/​synthetic.mdx Converts synthetic-data page.
astro-site/​src/​content/​docs/​datasets/​stages.mdx Converts STAGES page.
astro-site/​src/​content/​docs/​datasets/​mesa.mdx Converts MESA page.
astro-site/​src/​content/​docs/​datasets/​index.mdx Adds canonical dataset index.
astro-site/​src/​content/​docs/​datasets/​cmidss.mdx Converts CMIDSS page.
astro-site/​src/​content/​docs/​datasets/​byod.mdx Converts custom-dataset guide.
astro-site/​scripts/​normalize-markdown.test.mjs Removes converter tests.
astro-site/​scripts/​normalize-markdown.mjs Removes Markdown normalizer.
astro-site/​scripts/​check-output.mjs Validates canonical routes and archive output.
astro-site/​scripts/​check-doc-examples.py Checks canonical MDX examples.
astro-site/​scripts/​canonical-content.test.mjs Adds canonical-content regression test.
astro-site/​scripts/​build-reference.mjs Preserves canonical redirects during API generation.
astro-site/​scripts/​build-notebooks.py Uses the explicit notebook archive.
astro-site/​scripts/​build-examples.mjs Generates downloads and publishes evidence.
astro-site/​scripts/​build-content.mjs Removes the MkDocs conversion adapter.
astro-site/​README.md Documents canonical source ownership.
astro-site/​public/​assets/​tasks/​stage/​demo-sleep-cycle-pie.html Tracks a static Plotly asset.
astro-site/​public/​assets/​guides/​stage/​ablation-dilation.html Tracks an ablation plot asset.
astro-site/​package.json Replaces conversion with targeted generators.
astro-site/​MIGRATION.md Records completion of the migration.
.gitignore Tracks canonical content while ignoring generated outputs.

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

Comment thread astro-site/scripts/canonical-content.test.mjs Outdated
Comment thread astro-site/scripts/build-notebooks.py
Comment thread HANDOFF.md Outdated
Comment thread astro-site/src/content/docs/modes/download.mdx Outdated
Copilot AI balanced review requested due to automatic review settings October 1, 2026 13:57

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copilot review overview

🔵 Needs a closer look

The broad documentation-source migration and route-preservation surface warrant final human review despite strong automated validation.

Review effort: Balanced
Findings: None

Resolved since last review (4)
Previously missed (4)

In code that hasn't changed since last review

Low severity Document both redirect configuration locations

astro-site/​README.md:22

This ownership guidance is incomplete: the legacy static redirects are still hard-coded in astro.config.mjs:35-40, so editing only src/redirects.json can miss existing redirects. Document both canonical locations (or move those entries into the JSON file).

Low severity Correct the split word Animation

astro-site/​src/​content/​docs/​datasets/​index.mdx:16

Correct the split word “Ani- mation” to “Animation.”

Low severity Correct the misspelling of leveraging

astro-site/​src/​content/​docs/​tasks/​detect.mdx:10

Correct the misspelling of “leveraging.”

Low severity Correct the misspelling of efficiency

astro-site/​src/​content/​docs/​zoo/​detect.mdx:49

Correct the misspelling of “efficiency.”

@apage224
apage224 merged commit ca3db58 into main Oct 1, 2026
9 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

docs: make Astro content canonical and retire MkDocs adapter

2 participants