docs: migrate sleepKIT to Astro

.github/workflows/docs.yaml

@@ -1,70 +1,69 @@
-name: Deploy to GitHub Pages
+name: Documentation
 
 on:
-  workflow_call:
-    inputs:
-      ref:
-        description: Git ref (branch, tag, or SHA) to publish from
-        required: false
-        type: string
+  pull_request:
+  push:
+    branches: [main]
   workflow_dispatch:
-    inputs:
-      ref:
-        description: Git ref (branch, tag, or SHA) to publish from
-        required: false
-        type: string
 
 permissions:
   contents: read
-  pages: write
-  id-token: write
 
 concurrency:
-  group: "pages"
-  cancel-in-progress: false
-
-# Default to bash
-defaults:
-  run:
-    shell: bash
+  group: docs-${{ github.event.pull_request.number || github.ref }}
+  cancel-in-progress: ${{ github.event_name == 'pull_request' }}
 
 jobs:
-  # Build job
   build:
+    name: Build and verify docs
     runs-on: ubuntu-latest
-
+    defaults:
+      run:
+        working-directory: astro-site
     steps:
-      - name: Checkout 🛎️
-        uses: actions/checkout@v4
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
         with:
-          ref: ${{ inputs.ref || github.ref }}
-      - name: Setup Pages
-        id: pages
-        uses: actions/configure-pages@v4
-      - name: Install uv
-        uses: astral-sh/setup-uv@v5
+          node-version: "24"
+          cache: npm
+          cache-dependency-path: astro-site/package-lock.json
+      - uses: actions/setup-python@v5
         with:
-            enable-cache: true
-      - name: Install and Build 🔧
-        env:
-          CI: ""
-          PUBLIC_URL: "${{ steps.pages.outputs.base_url }}/"
-        run: |
-          uv sync --only-group docs
-          uv run mkdocs build
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v3
+          python-version: "3.12"
+      - uses: astral-sh/setup-uv@v6
+      - run: npm ci
+      - run: npx playwright install --with-deps chromium
+      - run: npm run check
+      - run: npm run build
+      - run: npm run check:output
+      - run: npm test
+      - uses: actions/upload-artifact@v4
+        if: always()
         with:
-          path: ./site
+          name: docs-preview
+          path: |
+            astro-site/dist
+            astro-site/test-results
+      - uses: actions/upload-pages-artifact@v3
+        if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+        with:
+          path: astro-site/dist
 
-  # Deployment job
   deploy:
+    name: Publish docs
+    if: github.ref == 'refs/heads/main' && github.event_name != 'pull_request'
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
     environment:
       name: github-pages
       url: ${{ steps.deployment.outputs.page_url }}
-    runs-on: ubuntu-latest
-    needs: build
+    concurrency:
+      group: pages
+      cancel-in-progress: false
     steps:
-      - name: Deploy to Pages 🚀
+      - uses: actions/configure-pages@v5
+      - uses: actions/deploy-pages@v4
         id: deployment
-        uses: actions/deploy-pages@v4

.github/workflows/release.yaml

@@ -83,15 +83,3 @@ jobs:
         run: uv build
       - name: Publish to PyPI 📦
         uses: pypa/gh-action-pypi-publish@release/v1
-
-  publish-docs:
-    needs: release-please
-    if: needs.release-please.outputs.releases_created == 'true' || needs.release-please.outputs.release_created == 'true'
-    permissions:
-      contents: read
-      pages: write
-      id-token: write
-    uses: ./.github/workflows/docs.yaml
-    with:
-      ref: ${{ needs.release-please.outputs.tag_name }}
-    secrets: inherit

.gitignore

@@ -184,3 +184,12 @@ cython_debug/
 #  and can be added to the global gitignore or merged into this file.  For a more nuclear
 #  option (not recommended) you can uncomment the following to ignore the entire idea folder.
 #.idea/
+
+# Generated documentation
+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/.nvmrc

@@ -0,0 +1 @@
+24

astro-site/MIGRATION.md

@@ -0,0 +1,47 @@
+# Migration review
+
+Tracking: AmbiqAI/sleepkit#43. Baseline: main e80e431.
+
+## Preserved
+
+- Existing documentation content and routes from docs/ and mkdocs.yml, with navigation refinements requested during review.
+- Installation tabs, admonitions, Markdown tables, math, five Mermaid diagrams, and embedded Plotly figures.
+- Training notebook code, three saved PNG figures, logs and text tables from the repository copy selected during review. The documentation and repository notebook copies have identical code cells but different saved outputs and metadata. The documentation copy has two PNG outputs; the repository copy has three. Neither original is changed.
+- Existing authored routes, plus redirects from generated MkDocs API routes to source-generated reference pages.
+- License documents and model-weight licensing boundaries.
+
+## Narrow repairs
+
+Two Python docstrings had unterminated example fences. Added closing fences and corrected sk.util to sk.utils in the plotting example. No runtime behavior changed.
+
+The old datasets/factory and features/factory API links now redirect to their defining package modules. A notebook feature-guide link is normalized for its rendered route.
+
+## Review fixes
+
+- Fixed snippet expansion that inserted blank lines between table rows. Added regression coverage for table whitespace and nested snippet indentation.
+- Normalize mixed-case Material callouts, unwrap example/install wrappers, and retain collapsed/expanded details. Guard every rendered page against leaked Material syntax, table text and image-width attributes.
+- Long JSON/YAML and Python examples have a compact preview, native expansion, syntax-highlighted full code, copy and download. Full examples remain in Markdown and LLM exports.
+- Removed duplicated Home navigation. Grouped staging and detection guides under their tasks. Shared architecture and component experiments, inherited from main PRs #33 and #36, are under Maintainer notes.
+- Reworked Modes overview and corrected stale task-parameter/import snippets and orphaned annotation markers. No runtime behavior changed.
+
+Validation: Astro check has no errors or warnings; build, output checks, four converter tests and ten browser tests pass. A browser sweep of all 59 authored Markdown pages at 390px found no viewport overflow or broken images. Inspected navigation, tabs, tables, modes and configuration screenshots, including dark mobile configuration. Clipboard content matches the JSON download.
+
+## Existing gaps retained for follow-up
+
+The synthetic dataset page no longer embeds the absent assets/segmentation_example.html; it explains synthesis and custom dataset integration. The detect page also names assets/sleep-detect-demo.html in commented content; that inactive content remains excluded.
+
+Broader task/API/content inconsistencies belong to the existing product-readiness issue #18. This migration does not establish model validity or rerun notebook training, dataset acquisition, or hardware deployment.
+
+## Deployment boundary
+
+PRs build and test the site; main and manual main dispatch publish Pages. The package release workflow no longer invokes the docs workflow. Package publishing jobs and version metadata are unchanged. No production deployment has been performed for this branch.
+
+## Navigation and installation refinement
+
+Five major sections: Home, Getting started, User guide, Tasks and Reference. Every content page has section membership while preserving existing URLs. The local section matcher is resolved only for HELIA's section-matching imports so its header and sidebar use the same route assignment. A build guard checks section coverage; browser checks confirm both the selected navbar link and scoped sidebar on historical routes. Mobile retains access to all five sections with the current section expanded.
+
+Landing installation examples are copyable Bash commands with no Termynal progress artifacts . Ten browser tests pass.
+
+## Public documentation boundary
+
+Private implementation API modules and their redirects are excluded. Shared architecture proposals, reusable-component experiments, feature-preparation implementation notes and unadopted draft license terms stay in the repository and are not published. Public task workflows and model licensing guidance remain. The public site now contains 55 authored Markdown pages, one notebook and 110 API modules (216 catalog symbols). Output checks reject internal routes and private modules in the catalog/reference model.

astro-site/README.md

@@ -0,0 +1,28 @@
+# sleepKIT documentation site
+
+The Astro/Starlight site reads the authored Markdown in `../docs` and the saved notebook in `../notebooks` and generates Python reference pages with Griffe. The Python package is inspected statically; no training dependencies or notebook execution are required.
+
+Use Node 24, Python 3.12 and uv:
+
+```sh
+npm ci
+npx playwright install chromium
+npm run dev -- --port 8774
+```
+
+Validation:
+
+```sh
+npm run check
+npm run build
+npm run check:output
+npm test
+```
+
+`prepare:docs` regenerates `src/content/docs`, `src/data` and `public`. Do not edit those directories. Edit Markdown under `../docs`, Python docstrings, or the owning scripts. `mkdocs.yml` supplies the existing navigation during migration. `.cache/conversion.json` records syntax conversions and items requiring visual inspection.
+
+The notebook page uses `notebooks/train-detect-model.ipynb`, preserving its saved outputs, three figures and downloadable original. The earlier `docs/guides/` copy is retained as an archive download. Neither source is overwritten. Historical notebook outputs do not establish validation against the latest package.
+
+The documentation workflow checks pull requests and publishes main to GitHub Pages. It can also be dispatched manually on main. It does not publish Python packages. Package publishing remains in the release workflows; documentation no longer depends on a package release.
+
+Public reference generation excludes underscore-prefixed implementation modules before rendering, so they do not appear in pages, catalog, search or machine-readable exports. `scripts/public-docs.mjs` lists repository-only maintainer/proposal pages omitted from publication. Their sources remain in the repository.

astro-site/astro.config.mjs

@@ -0,0 +1,89 @@
+import { defineConfig } from "astro/config";
+import { unified } from "@astrojs/markdown-remark";
+import starlight from "@astrojs/starlight";
+import react from "@astrojs/react";
+import { heliaStarlight } from "@ambiqai/helia-ui/starlight";
+import rehypeMermaid from "rehype-mermaid";
+import remarkMath from "remark-math";
+import rehypeKatex from "rehype-katex";
+import redirects from "./src/data/redirects.json" with { type: "json" };
+import { sections } from "./src/navigation.mjs";
+import { fileURLToPath } from "node:url";
+export default defineConfig({
+  vite: {
+    plugins: [
+      {
+        name: "sleepkit-section-membership",
+        enforce: "pre",
+        resolveId(source, importer) {
+          // Historical page URLs do not share the section's URL prefix.
+          if (
+            source === "./sections" &&
+            importer?.includes("/@ambiqai/helia-ui/starlight/")
+          )
+            return fileURLToPath(
+              new URL("./src/section-matcher.ts", import.meta.url),
+            );
+        },
+      },
+    ],
+  },
+  site: "https://ambiqai.github.io",
+  base: "/sleepkit",
+  redirects: {
+    ...redirects,
+    "/api/sleepkit/datasets/factory":
+      "/sleepkit/reference/api/sleepkit/datasets/",
+    "/api/sleepkit/features/factory":
+      "/sleepkit/reference/api/sleepkit/features/",
+    "/api": "/sleepkit/reference/",
+    "/guides/train-detect-model.ipynb": "/sleepkit/guides/train-detect-model/",
+  },
+  markdown: {
+    processor: unified({
+      remarkPlugins: [remarkMath],
+      rehypePlugins: [rehypeKatex, [rehypeMermaid, { strategy: "inline-svg" }]],
+    }),
+  },
+  integrations: [
+    react(),
+    starlight({
+      components: { Hero: "./src/components/HomeHero.astro" },
+      title: "sleepKIT",
+      description: "AI development kit for sleep monitoring on Ambiq devices.",
+      favicon: "/assets/favicon.png",
+      customCss: [
+        "./src/styles/site.css",
+        "@ambiqai/helia-ui/mermaid.css",
+        "katex/dist/katex.min.css",
+      ],
+      plugins: [
+        heliaStarlight({
+          accent: "kit-sleep",
+          sections,
+          sidebar: "always",
+          header: {
+            title: "sleepKIT",
+            hub: {
+              label: "HELIA",
+              href: "https://ambiqai.github.io/helia-developer-hub/",
+            },
+          },
+          discoverability: {
+            markdown: true,
+            llms: true,
+            jsonLd: true,
+            ogImage: true,
+          },
+          footer: {
+            logo: "ambiq",
+            tagline: "Part of the Ambiq HELIA AI platform",
+            links: [
+              { label: "GitHub", href: "https://github.com/AmbiqAI/sleepkit" },
+            ],
+          },
+        }),
+      ],
+    }),
+  ],
+});