Update docs

Implemented multi-version documentation.

  Key results:

  - 217 published GitHub releases selectable
  - 88 deduplicated API snapshots
  - Version-specific installation and API pages
  - Search, sidebar, version selector, release history, dark mode
  - Responsive desktop/mobile design
  - Vercel-compatible Next.js build
  - CI documentation workflow
  - npm run lint and npm run build pass
  - Production routes and 404 behavior verified

  Main files:

  - metbit/docs/app/docs/[version]/page.tsx
  - metbit/docs/scripts/sync_version_docs.py
  - metbit/docs/content/generated/releases.json
  - metbit/docs/README.md

Author: aeiwz

.github/workflows/docs.yml

@@ -0,0 +1,45 @@
+name: Documentation
+
+on:
+  pull_request:
+    paths:
+      - "docs/**"
+      - "metbit/**"
+      - ".github/workflows/docs.yml"
+  push:
+    branches: [main]
+    paths:
+      - "docs/**"
+      - "metbit/**"
+      - ".github/workflows/docs.yml"
+
+permissions:
+  contents: read
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    defaults:
+      run:
+        working-directory: docs
+    steps:
+      - name: Check out repository with tags
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v4
+        with:
+          node-version: 22
+          cache: npm
+          cache-dependency-path: docs/package-lock.json
+
+      - name: Install dependencies
+        run: npm ci
+
+      - name: Lint
+        run: npm run lint
+
+      - name: Build
+        run: npm run build

docs/README.md

@@ -1,15 +1,14 @@
 # metbit documentation site
 
-This is the Next.js documentation app for `metbit`. It uses the App Router and MDX pages for guides and API reference content.
+This is the Next.js documentation app for `metbit`. It provides release-specific
+guides and API reference pages generated from each published GitHub release.
 
 ## Structure
 
-- `app/` — App Router
-  - `page.tsx` — Landing page
-  - `docs/` — Docs section with a sidebar layout
-    - `overview/page.mdx`
-    - `getting-started/page.mdx`
-    - `api/` — API reference pages
+- `app/docs/[version]/` — version-aware documentation routes
+- `content/generated/releases.json` — published release manifest
+- `content/generated/snapshots/` — deduplicated API snapshots parsed from Git tags
+- `scripts/sync_version_docs.py` — release and API documentation generator
 - `globals.css` — global and docs layout styles
 - `next.config.js` — MDX-enabled config
 - `package.json` — scripts and dependencies
@@ -21,18 +20,29 @@ This is the Next.js documentation app for `metbit`. It uses the App Router and M
 3. Dev server: `npm run dev`
 4. Open: http://localhost:3000
 
+## Refresh versioned documentation
+
+The sync script reads GitHub Releases and the corresponding local Git tags:
+
+```bash
+npm run docs:sync
+```
+
+Run `git fetch --tags` first when new releases have been published. The
+generator stores identical parsed APIs once and maps every release to its
+matching snapshot, keeping the Vercel deployment compact.
+
 ## Authoring notes
 
-- Add new docs by creating folders under `app/docs/<slug>/page.mdx`.
-- API pages live under `app/docs/api/<slug>/page.mdx`.
-- Prefer root imports in examples, for example `from metbit import pca, opls_da`.
-- Use subpackage imports only when documenting advanced internals, for example `from metbit.nmr.alignment import PeakAligner`.
-- Keep code examples runnable with current package exports.
-- MDX allows mixing Markdown with React components.
+- New releases require a GitHub Release and a matching local Git tag.
+- API pages are generated from source signatures and docstrings; improve the
+  Python docstring when generated documentation is incomplete.
+- Historical releases may not support current Python versions or dependencies.
 - Icons come from `react-icons`.
 
 ## Maintenance checklist
 
-- Update quick-start examples when public imports change in `metbit/__init__.py`.
-- Keep the API index aligned with public exports and important subpackage utilities.
+- Run `npm run docs:sync` after publishing a release.
+- Review the generated manifest and release count.
+- Check one current and one historical version.
 - Run `npm run build` before publishing the docs site.

docs/app/components/DocsSearch.tsx

@@ -0,0 +1,54 @@
+'use client'
+
+import { useMemo, useState } from 'react'
+import { FiSearch, FiX } from 'react-icons/fi'
+
+type SearchItem = {
+  label: string
+  detail: string
+  href: string
+}
+
+export default function DocsSearch({ items }: { items: SearchItem[] }) {
+  const [query, setQuery] = useState('')
+  const results = useMemo(() => {
+    const normalized = query.trim().toLowerCase()
+    if (!normalized) return []
+    return items
+      .filter((item) => `${item.label} ${item.detail}`.toLowerCase().includes(normalized))
+      .slice(0, 12)
+  }, [items, query])
+
+  return (
+    <div className="docsSearch">
+      <FiSearch aria-hidden />
+      <input
+        aria-label="Search documentation"
+        placeholder="Search documentation"
+        value={query}
+        onChange={(event) => setQuery(event.target.value)}
+      />
+      {query ? (
+        <button type="button" aria-label="Clear search" onClick={() => setQuery('')}>
+          <FiX aria-hidden />
+        </button>
+      ) : (
+        <kbd>/</kbd>
+      )}
+      {query && (
+        <div className="searchResults">
+          {results.length ? (
+            results.map((result) => (
+              <a key={result.href} href={result.href} onClick={() => setQuery('')}>
+                <strong>{result.label}</strong>
+                <span>{result.detail}</span>
+              </a>
+            ))
+          ) : (
+            <p>No documentation found.</p>
+          )}
+        </div>
+      )}
+    </div>
+  )
+}

docs/app/components/MetbitMark.tsx

@@ -0,0 +1,8 @@
+export default function MetbitMark() {
+  return (
+    <svg className="metbitMark" viewBox="0 0 44 30" role="img" aria-label="metbit">
+      <path d="M2 26h40" />
+      <path d="M5 26V20M10 26V13M15 26V4M20 26V17M25 26V9M30 26V21M35 26V15M40 26V23" />
+    </svg>
+  )
+}

docs/app/components/ThemeToggle.tsx

@@ -1,4 +1,5 @@
-"use client"
+'use client'
+
 import { useEffect, useState } from 'react'
 import { FiSun, FiMonitor, FiMoon } from 'react-icons/fi'
 
@@ -46,36 +47,37 @@ export default function ThemeToggle() {
   }
 
   return (
-    <div className="themeToggle" aria-label="Theme">
-      <div className="seg" role="group" aria-label="Theme toggle">
-        <button
-          type="button"
-          className={mode==='light' ? 'active' : ''}
-          onClick={() => choose('light')}
-          aria-pressed={mode==='light'}
-          aria-label="Light theme"
-        >
-          <FiSun aria-hidden /> Light
-        </button>
-        <button
-          type="button"
-          className={mode==='system' ? 'active' : ''}
-          onClick={() => choose('system')}
-          aria-pressed={mode==='system'}
-          aria-label="System theme"
-        >
-          <FiMonitor aria-hidden /> System
-        </button>
-        <button
-          type="button"
-          className={mode==='dark' ? 'active' : ''}
-          onClick={() => choose('dark')}
-          aria-pressed={mode==='dark'}
-          aria-label="Dark theme"
-        >
-          <FiMoon aria-hidden /> Dark
-        </button>
-      </div>
+    <div className="themeToggle" role="group" aria-label="Color theme">
+      <button
+        type="button"
+        className={mode === 'light' ? 'active' : ''}
+        onClick={() => choose('light')}
+        aria-pressed={mode === 'light'}
+        aria-label="Use light theme"
+        title="Light theme"
+      >
+        <FiSun aria-hidden />
+      </button>
+      <button
+        type="button"
+        className={mode === 'system' ? 'active' : ''}
+        onClick={() => choose('system')}
+        aria-pressed={mode === 'system'}
+        aria-label="Use system theme"
+        title="System theme"
+      >
+        <FiMonitor aria-hidden />
+      </button>
+      <button
+        type="button"
+        className={mode === 'dark' ? 'active' : ''}
+        onClick={() => choose('dark')}
+        aria-pressed={mode === 'dark'}
+        aria-label="Use dark theme"
+        title="Dark theme"
+      >
+        <FiMoon aria-hidden />
+      </button>
     </div>
   )
 }

docs/app/components/VersionSelector.tsx

@@ -0,0 +1,44 @@
+'use client'
+
+import { usePathname, useRouter } from 'next/navigation'
+
+import type { Release } from '@/lib/versioned-docs'
+
+export default function VersionSelector({
+  releases,
+  current,
+}: {
+  releases: Release[]
+  current: string
+}) {
+  const pathname = usePathname()
+  const router = useRouter()
+
+  function selectVersion(tag: string) {
+    const segments = pathname.split('/')
+    if (segments[1] === 'docs' && segments[2]) {
+      segments[2] = encodeURIComponent(tag)
+      const stableSuffix = segments[3]
+      if (stableSuffix === 'getting-started' || stableSuffix === 'releases' || stableSuffix === 'api' && segments.length === 4) {
+        router.push(segments.join('/'))
+      } else {
+        router.push(`/docs/${encodeURIComponent(tag)}`)
+      }
+      return
+    }
+    router.push(`/docs/${encodeURIComponent(tag)}`)
+  }
+
+  return (
+    <label className="versionControl">
+      <span>Version</span>
+      <select value={current} onChange={(event) => selectVersion(event.target.value)}>
+        {releases.map((release) => (
+          <option key={release.tag} value={release.tag}>
+            {release.version}
+          </option>
+        ))}
+      </select>
+    </label>
+  )
+}