Skip to content

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

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. The five identical documentation notebook copies are removed in favor of notebooks/.

Validation:

  • Clean npm install, build, type checks, output/link checks and locked dependency verification passed.
  • Generation-preserves-authored-content regression passed.
  • 8 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 #47

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

Canonical notebook downloads retain links to the deleted docs/guides paths, and two migrated page titles contain spelling defects.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
What changed in this PR

Makes Astro/Starlight content canonical while removing the retired MkDocs adapter and preserving generated API pages, notebook guides, downloads, assets, and redirects.

Changes:

  • Removes MkDocs sources, tooling, dependencies, and duplicate notebook copies.
  • Promotes Astro content, navigation, redirects, and assets to canonical sources.
  • Adds regression checks for generated output and authored-content preservation.
File Description
scripts/​gen_ref_pages.py Removes MkDocs API generator.
pyproject.toml Removes MkDocs documentation dependencies.
mkdocs.yml Removes retired MkDocs configuration.
HANDOFF.md Updates migration status and validation notes.
docs/​usage/​python.md Removes legacy Python guide.
docs/​usage/​cli.md Removes legacy CLI guide.
docs/​tasks/​segmentation.md Removes legacy segmentation page.
docs/​tasks/​index.md Removes legacy task index.
docs/​tasks/​diagnostic.md Removes legacy diagnostic page.
docs/​tasks/​beat.md Removes legacy beat page.
docs/​quickstart.md Removes legacy quickstart.
docs/​overrides/​main.html Removes MkDocs template override.
docs/​modes/​train.md Removes legacy training page.
docs/​modes/​index.md Removes legacy workflow index.
docs/​modes/​export.md Removes legacy export page.
docs/​modes/​evaluate.md Removes legacy evaluation page.
docs/​js/​termynal.js Removes MkDocs terminal widget.
docs/​js/​custom.js Removes legacy documentation scripts.
docs/​index.md Removes legacy homepage.
docs/​guides/​index.md Removes legacy guide index.
docs/​datasets/​qtdb.md Removes legacy QTDB page.
docs/​datasets/​ludb.md Removes legacy LUDB page.
docs/​datasets/​index.md Removes legacy dataset index.
docs/​css/​termynal.css Removes terminal widget styles.
docs/​css/​mkdocstrings.css Removes Mkdocstrings styles.
docs/​css/​custom.css Removes legacy theme styles.
docs/​assets/​zoo/​segmentation/​segmentation-model-zoo-table.md Removes migrated model table snippet.
docs/​assets/​zoo/​seg-ppg-2-tcn-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​seg-4-tcn-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​seg-4-tcn-lg/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​seg-2-tcn-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​rhythm/​rhythm-model-zoo-table.md Removes migrated rhythm table.
docs/​assets/​zoo/​diagnostic/​results.md Removes obsolete diagnostic snippet.
docs/​assets/​zoo/​denoise/​denoise-model-zoo-table.md Removes migrated denoise table.
docs/​assets/​zoo/​den-tcn-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​den-tcn-lg/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​den-ppg-tcn-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​beat/​beat-model-zoo-table.md Removes migrated beat table.
docs/​assets/​zoo/​beat-3-eff-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​beat-2-eff-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​arr-4-eff-sm/​results.md Removes migrated result snippet.
docs/​assets/​zoo/​arr-2-eff-sm/​results.md Removes migrated result snippet.
docs/​assets/​usage/​python-configuration.md Removes migrated Python example.
docs/​assets/​usage/​json-configuration.md Removes migrated JSON example.
docs/​assets/​tasks/​segmentation/​segmentation-classes.md Removes migrated class table.
docs/​assets/​tasks/​rhythm/​rhythm-classes.md Removes migrated class table.
docs/​assets/​tasks/​beat/​beat-classes.md Removes migrated class table.
docs/​assets/​modes/​python-demo-snippet.md Removes migrated demo snippet.
astro-site/​src/​redirects.json Makes static legacy redirects canonical.
astro-site/​src/​navigation.mjs Makes authored navigation canonical.
astro-site/​src/​content/​docs/​zoo/​seg-ppg-2-tcn-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​seg-4-tcn-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​seg-4-tcn-lg.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​seg-2-tcn-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​index.mdx Canonicalizes the model-zoo index.
astro-site/​src/​content/​docs/​zoo/​den-tcn-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​den-tcn-lg.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​den-ppg-tcn-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​beat-3-eff-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​beat-2-eff-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​arr-4-eff-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​zoo/​arr-2-eff-sm.mdx Canonicalizes the model page.
astro-site/​src/​content/​docs/​usage/​python.mdx Adds canonical Python usage content.
astro-site/​src/​content/​docs/​usage/​cli.mdx Adds canonical CLI content.
astro-site/​src/​content/​docs/​tasks/​segmentation.mdx Adds canonical segmentation content.
astro-site/​src/​content/​docs/​tasks/​rhythm.mdx Canonicalizes rhythm content.
astro-site/​src/​content/​docs/​tasks/​index.mdx Adds canonical task index.
astro-site/​src/​content/​docs/​tasks/​diagnostic.mdx Adds canonical diagnostic content.
astro-site/​src/​content/​docs/​tasks/​denoise.mdx Canonicalizes denoise content.
astro-site/​src/​content/​docs/​tasks/​byot.mdx Canonicalizes BYOT content.
astro-site/​src/​content/​docs/​tasks/​beat.mdx Adds canonical beat content.
astro-site/​src/​content/​docs/​modes/​index.mdx Adds canonical workflow overview.
astro-site/​src/​content/​docs/​modes/​download.mdx Canonicalizes download documentation.
astro-site/​src/​content/​docs/​modes/​demo.mdx Canonicalizes demo documentation.
astro-site/​src/​content/​docs/​modes/​configuration.mdx Canonicalizes configuration documentation.
astro-site/​src/​content/​docs/​models/​index.mdx Canonicalizes model documentation.
astro-site/​src/​content/​docs/​models/​byom.mdx Canonicalizes BYOM documentation.
astro-site/​src/​content/​docs/​index.mdx Adds the canonical homepage.
astro-site/​src/​content/​docs/​guides/​rhythm-demo.mdx Canonicalizes the rhythm tutorial.
astro-site/​src/​content/​docs/​guides/​index.mdx Adds canonical guide navigation.
astro-site/​src/​content/​docs/​guides/​evb-setup.mdx Canonicalizes EVB setup guidance.
astro-site/​src/​content/​docs/​datasets/​synthetic.mdx Canonicalizes synthetic dataset docs.
astro-site/​src/​content/​docs/​datasets/​qtdb.mdx Adds canonical QTDB documentation.
astro-site/​src/​content/​docs/​datasets/​ptbxl.mdx Canonicalizes PTB-XL documentation.
astro-site/​src/​content/​docs/​datasets/​mitbih.mdx Canonicalizes MIT-BIH documentation.
astro-site/​src/​content/​docs/​datasets/​ludb.mdx Adds canonical LUDB documentation.
astro-site/​src/​content/​docs/​datasets/​lsad.mdx Canonicalizes LSAD documentation.
astro-site/​src/​content/​docs/​datasets/​index.mdx Adds canonical dataset index.
astro-site/​src/​content/​docs/​datasets/​icentia11k.mdx Canonicalizes Icentia11k documentation.
astro-site/​src/​content/​docs/​datasets/​byod.mdx Canonicalizes BYOD documentation.
astro-site/​scripts/​test-build-notebooks.py Tests notebooks from their canonical directory.
astro-site/​scripts/​normalize-markdown.test.mjs Removes obsolete converter tests.
astro-site/​scripts/​normalize-markdown.mjs Removes the Markdown compatibility adapter.
astro-site/​scripts/​check-output.mjs Validates canonical pages and notebook downloads.
astro-site/​scripts/​canonical-content.test.mjs Guards authored sources against generation changes.
astro-site/​scripts/​build-reference.mjs Merges canonical redirects with API redirects.
astro-site/​scripts/​build-notebooks.py Generates guides from canonical notebooks.
astro-site/​scripts/​build-examples.mjs Generates downloads from authored examples.
astro-site/​scripts/​build-content.mjs Removes the MkDocs-to-Astro converter.
astro-site/​README.md Documents canonical and generated sources.
astro-site/​public/​assets/​zoo/​arr-2-eff-sm/​confusion_matrix_test.html Tracks a canonical interactive asset.
astro-site/​package.json Replaces conversion with focused generators and checks.
astro-site/​MIGRATION.md Records the canonical-source cutover.
AGENTS.md Updates repository documentation guidance.
.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/build-notebooks.py
Copilot AI balanced review requested due to automatic review settings October 1, 2026 13:57
@apage224
apage224 merged commit e431edf into main Oct 1, 2026
5 checks passed

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

Several canonical examples reference nonexistent APIs or run the wrong mode, and generated-content safeguards have coverage gaps.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
Resolved since last review (1)
Previously missed (16)

In code that hasn't changed since last review

Medium severity Standalone example references undefined self

astro-site/​src/​content/​docs/​datasets/​icentia11k.mdx:29

This standalone example has no self, so copying it raises NameError before the generator is created. Call the dataset instance defined above directly.

Medium severity Standalone example references undefined self

astro-site/​src/​content/​docs/​datasets/​lsad.mdx:29

This standalone example has no self, so copying it raises NameError before the generator is created. Call the dataset instance defined above directly.

Medium severity Standalone example references undefined self

astro-site/​src/​content/​docs/​datasets/​ptbxl.mdx:29

This standalone example has no self, so copying it raises NameError before the generator is created. Call the dataset instance defined above directly.

Medium severity CLI example uses export instead of demo mode

astro-site/​src/​content/​docs/​modes/​demo.mdx:154

The CLI tab is presented as a demo invocation, but -m export exports a model instead of running the segmentation demo. Use the demo mode here.

This issue also appears on line 165 of the same file.

Medium severity Dataset download example uses unavailable APIs

astro-site/​src/​content/​docs/​datasets/​mitbih.mdx:33

This example references two unavailable APIs: neither hk.HKDownloadParams nor hk.datasets.download_datasets exists, and mitbih is not registered in heartkit/datasets/__init__.py. The page needs either an example using a supported dataset and HKTaskParams/task.download, or the missing MIT-BIH integration must be restored.

Low severity Comment incorrectly describes class 0 mapping

astro-site/​src/​content/​docs/​tasks/​rhythm.mdx:123

Class 0 is NSR in the table above, so this comment incorrectly describes the mapping as “None to None.”

Medium severity Subclass example uses nonexistent parameter classes

astro-site/​src/​content/​docs/​tasks/​byot.mdx:14

The enclosed subclass example annotates all four methods with mode-specific parameter classes that do not exist. HKTask declares every mode with HKTaskParams (heartkit/tasks/task.py:48-82), so copying this example currently fails while the class annotations are evaluated.

This issue also appears on line 48 of the same file.

Low severity Remove duplicated word be

astro-site/​src/​content/​docs/​models/​index.mdx:70

Remove the duplicated “be” so the sentence is grammatical.

Medium severity Standalone example references undefined self

astro-site/​src/​content/​docs/​datasets/​ludb.mdx:29

This standalone example has no self, so copying it raises NameError before the generator is created. Call the dataset instance defined above directly.

Medium severity Standalone example references undefined self

astro-site/​src/​content/​docs/​datasets/​qtdb.mdx:27

This standalone example has no self, so copying it raises NameError before the generator is created. Call the dataset instance defined above directly.

Medium severity Escape rhythm table has a column mismatch

astro-site/​src/​content/​docs/​tasks/​beat.mdx:21

This row has one more cell than the four-column header because each escape rhythm name is separated from its details. The rendered table shifts the atrial, junctional, and ventricular descriptions into the wrong columns.

Low severity Fix misspelling of flexible

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

Correct the misspelling of “flexible.”

This issue also appears in the following locations of the same file:

  • line 130
  • line 159
Low severity Fix misspelling of implements

astro-site/​src/​content/​docs/​modes/​index.mdx:10

Correct the misspelling of “implements.”

Low severity Fix misspelling of arrhythmias

astro-site/​src/​content/​docs/​tasks/​index.mdx:28

Correct the misspelling of “arrhythmias.”

Low severity Section incorrectly describes TaskFactory

astro-site/​src/​content/​docs/​tasks/​index.mdx:44

This section describes TaskFactory, not the dataset factory.

This issue also appears on line 59 of the same file.

Low severity Fix misspelling of tasks

astro-site/​src/​content/​docs/​usage/​python.mdx:8

Correct the misspelling of “tasks.”

entry.isDirectory() ? walk(join(dir, entry.name)) : [join(dir, entry.name)],
);
const snapshot = () => Object.fromEntries([
...walk("src/content/docs").filter((p) => p.endsWith(".mdx") && !p.startsWith("src/content/docs/reference/")),
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