Skip to content

docs: migrate sleepKIT to Astro - #44

Merged
apage224 merged 3 commits into
mainfrom
codex/sleepkit-astro
Sep 30, 2026
Merged

apage224 merged 3 commits into
mainfrom
codex/sleepkit-astro

Conversation

@apage224

@apage224 apage224 commented Sep 30, 2026 •

Copy link
Copy Markdown
Collaborator

Problem and result

Replace the MkDocs site with Astro/Starlight and HELIA styling while preserving authored routes, notebook examples and Python API coverage. The landing page introduces the toolkit, scoped navigation reduces nesting, and conversion fixes restore tables, callouts, tabs and configuration examples.

Approach

  • Generate 55 authored pages, a saved-output notebook page and 110 public Python API module pages; retain historical API redirects and search/discovery exports.
  • Exclude private implementation modules, maintainer proposals and draft license terms from pages, navigation, search and machine-readable exports; retain their repository sources.
  • Render the more complete repository notebook with three saved figures. Preserve both original notebook downloads, without executing training.
  • Correct documented factory examples, feature fields and historical experiment context. Python source changes are docstring repairs only.
  • Build/test on PRs and deploy Pages from main or manual dispatch, independently of package releases.

Validation

Astro check: zero errors/warnings. Production build, internal links across 314 HTML files, source-based feature checks, four converter tests and ten Playwright tests pass. Desktop/mobile/light/dark layouts inspected; all authored pages received a rendered review.

Boundaries and follow-up

No notebook training, dataset acquisition, hardware deployment or full package installation rerun. Saved results remain historical. Code/model refresh and Hugging Face publication are separate follow-up work. Site deployment will be verified after merge.

Closes #43

Copilot AI balanced review requested due to automatic review settings September 30, 2026 12:56

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

Published model and configuration examples contain unsupported parameter names that fail or are silently ignored.

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

Open (2)
What changed in this PR

Migrates sleepKIT documentation from MkDocs to Astro/Starlight, adding generated API/notebook content, HELIA styling, validation, and independent Pages deployment.

Changes:

  • Adds the Astro site, converters, navigation, styling, and automated tests.
  • Updates documentation, examples, feature contracts, and historical notes.
  • Separates documentation deployment from package releases.
File Description
sleepkit/​utils/​plotting.py Repairs plotting docstring example.
sleepkit/​models/​__init__.py Converts the TCN documentation example.
sleepkit/​datasets/​augmentation.py Closes an example fence.
docs/​usage/​python.md Updates Python usage examples.
docs/​usage/​cli.md Corrects supported CLI tasks.
docs/​tasks/​stage.md Adds staging links and chart markup.
docs/​tasks/​index.md Removes the legacy recap.
docs/​tasks/​detect.md Makes class mapping valid JSON.
docs/​tasks/​arousal.md Retains the route as a compatibility notice.
docs/​tasks/​apnea.md Corrects Hypopnea spelling.
docs/​staging-training.md Corrects split-manifest documentation.
docs/​shared-foundation.md Reframes maintainer architecture notes.
docs/​reusable-blocks.md Reframes experimental component notes.
docs/​quickstart.md Modernizes configuration-driven examples.
docs/​modes/​train.md Updates training flow and examples.
docs/​modes/​index.md Replaces the modes landing page.
docs/​modes/​export.md Updates export documentation.
docs/​modes/​evaluate.md Updates evaluation documentation.
docs/​modes/​demo.md Corrects demo and custom backend examples.
docs/​models/​index.md Updates registered models and configuration.
docs/​models/​byom.md Aligns custom-model input naming.
docs/​index.md Rebuilds the landing-page content.
docs/​guides/​index.md Reorganizes user guides.
docs/​features/​index.md Corrects feature documentation.
docs/​features/​fs_w_pa_14.md Documents task-specific label datasets.
docs/​features/​fs_w_p_5.md Adds signal quality and label paths.
docs/​features/​fs_w_a_5.md Corrects the detection-label path.
docs/​features/​fs_h_e_10.md Corrects EEG terminology and labels.
docs/​features/​fs_c_ear_9.md Corrects feature count and sensors.
docs/​features/​byofs.md Updates the custom-feature skeleton.
docs/​detection-source-alignment.md Records the adopted label workflow.
docs/​detection-recipe.md Updates preprocessing and validation status.
docs/​detection-preparation-performance.md Adds maintainer-note context.
docs/​detection-label-policy.md Marks the checkpoint as historical.
docs/​detection-evaluation-protocol.md Updates completed follow-up status.
docs/​detection-annotated-dataset.md Links completed comparison work.
docs/​datasets/​ysyw.md Removes unsupported arousal integration.
docs/​datasets/​synthetic.md Clarifies standalone synthesis integration.
docs/​datasets/​stages.md Removes unsupported arousal integration.
docs/​datasets/​mesa.md Removes unsupported arousal integration.
docs/​datasets/​cmidss.md Corrects source and download instructions.
docs/​datasets/​byod.md Replaces the custom-dataset example.
docs/​assets/​usage/​python-configuration.md Corrects sleepKIT aliases.
docs/​assets/​usage/​json-configuration.md Marks configuration as JSON.
astro-site/​tsconfig.json Adds strict Astro TypeScript configuration.
astro-site/​tests/​site.spec.ts Adds browser-level documentation tests.
astro-site/​src/​styles/​site.css Adds sleepKIT site styling.
astro-site/​src/​section-matcher.ts Maps historical routes to sections.
astro-site/​src/​navigation.mjs Defines scoped site navigation.
astro-site/​src/​content.config.ts Configures Starlight content loading.
astro-site/​src/​components/​HomeHero.astro Adds the custom landing hero.
astro-site/​src/​components/​ConfigExample.astro Adds expandable configuration examples.
astro-site/​scripts/​publish-reference.mjs Publishes generated API Markdown.
astro-site/​scripts/​normalize-markdown.test.mjs Tests Markdown conversion behavior.
astro-site/​scripts/​normalize-markdown.mjs Normalizes MkDocs syntax.
astro-site/​scripts/​check-output.mjs Validates generated site output.
astro-site/​scripts/​check-doc-examples.py Checks examples and feature contracts.
astro-site/​scripts/​build-reference.mjs Generates static Python API pages.
astro-site/​scripts/​build-notebooks.py Publishes saved notebook outputs.
astro-site/​scripts/​build-content.mjs Converts authored documentation.
astro-site/​README.md Documents site development and validation.
astro-site/​playwright.config.ts Configures browser tests.
astro-site/​package.json Defines Astro dependencies and scripts.
astro-site/​MIGRATION.md Records migration scope and validation.
astro-site/​astro.config.mjs Configures Astro, Starlight, and HELIA.
astro-site/​.nvmrc Selects Node 24.
.gitignore Ignores generated site artifacts.
.github/​workflows/​release.yaml Decouples docs from package releases.
.github/​workflows/​docs.yaml Adds independent docs CI and deployment.

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

Comment thread docs/quickstart.md


---
--8<-- "assets/usage/json-configuration.md"
Comment thread sleepkit/models/__init__.py Outdated
Copilot AI balanced review requested due to automatic review settings September 30, 2026 13:06

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

Several newly presented examples select the wrong task or use an unsupported TCN parameter.

Review effort: Balanced
Findings: 1 Medium severity

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

In code that hasn't changed since last review

Medium severity Select the task matching the sleep-detection configuration

docs/​quickstart.md:144

The configuration displayed immediately below is a sleep-detection configuration (FS-W-A-5, detect_labels, and WAKE/SLEEP classes), but this snippet selects the staging task. As written, the quickstart labels a detection run as staging; select detect or provide a matching staging configuration.

Medium severity Align the workflow task with the detection configuration

docs/​usage/​python.md:75

The included example configuration uses detection features and detect_labels, while this workflow selects stage. A reader following the complete example therefore runs detection settings under the staging task name; use the detection key or show a staging configuration instead.

Medium severity Use the correct model name field

sleepkit/​models/​__init__.py:64

helia-edge==0.4.1 defines this field as name, not model_name. Because the parameter model ignores unknown fields, the example silently leaves the model name at its default instead of applying "tcn".

Low severity Remove the extra space before the period

astro-site/​MIGRATION.md:43

Remove the stray space before the period.

Copilot AI balanced review requested due to automatic review settings September 30, 2026 14:33

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 custom-backend guide references top-level sleepKIT attributes that do not exist, causing its revised examples to fail.

Review effort: Balanced
Findings: 1 Medium severity

Open (1)
Previously missed (1)

In code that hasn't changed since last review

Medium severity Fix backend guide imports for InferenceBackend and BackendFactory

docs/​modes/​demo.md:83

The backend guide cannot run as written: sleepkit does not export InferenceBackend or BackendFactory at the top level (sleepkit/__init__.py:11-20); both live under sleepkit.backends. The class definition and the later registration/lookup snippets therefore raise AttributeError. Use sk.backends.InferenceBackend and sk.backends.BackendFactory, or import both from sleepkit.backends, throughout this section.

@apage224
apage224 merged commit 18639ad into main Sep 30, 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: migrate sleepKIT to Astro

2 participants