Merge pull request #70 from amrit110/feat/mike-versioned-docs

feat: add mike-based versioned docs with version selector

Author: Dinghye

.github/workflows/docs.yml

@@ -5,10 +5,14 @@ on:
     paths:
       - "docs/**"
       - "mkdocs.yml"
+      - "pyproject.toml"
+    tags:
+      - "v*.*.*"
   pull_request:
     paths:
       - "docs/**"
       - "mkdocs.yml"
+      - "pyproject.toml"
 
 permissions:
   contents: write
@@ -21,18 +25,43 @@ jobs:
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - run: pip install mkdocs-material pymdown-extensions
+      - run: pip install mkdocs-material pymdown-extensions mike
       - name: Build docs (strict)
         run: mkdocs build --strict
 
-  deploy:
+  deploy-dev:
     if: github.event_name == 'push' && github.ref == 'refs/heads/main'
     needs: validate
     runs-on: ubuntu-latest
     steps:
       - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - run: pip install mkdocs-material pymdown-extensions mike
+      - run: git config user.name "github-actions[bot]"
+      - run: git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Deploy dev docs
+        run: mike deploy --push --update-aliases dev
+
+  deploy-release:
+    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    needs: validate
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
       - uses: actions/setup-python@v5
         with:
           python-version: "3.12"
-      - run: pip install mkdocs-material pymdown-extensions
-      - run: mkdocs gh-deploy --force
+      - run: pip install mkdocs-material pymdown-extensions mike
+      - run: git config user.name "github-actions[bot]"
+      - run: git config user.email "github-actions[bot]@users.noreply.github.com"
+      - name: Deploy versioned docs
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          mike deploy --push --update-aliases "$VERSION" latest
+          mike set-default --push latest

.gitignore

@@ -1,4 +1,6 @@
 data/
+.venv/
+/site/
 __pycache__/
 *.py[cod]
 .ruff_cache/

CHANGELOG.md

@@ -13,6 +13,8 @@ The format is based on Keep a Changelog, and the project follows Semantic Versio
 - Standardised NumPy docstrings across all public functions and classes in `export.py`, `inspect.py`, `writers.py`, and the `tools/` and `providers/` layers. No behaviour changes.
 ### Added
 
+- Versioned documentation with a version selector powered by `mike` and MkDocs Material. Each release tag deploys a pinned version; pushes to `main` update a `dev` alias. The `mike`, `mkdocs-material`, and `pymdown-extensions` packages are now included in the `[dev]` optional group.
+
 - `load_export(path)` reader API that loads any export produced by `export_batch(...)` — both combined (single file) and per-item (directory) layouts — and returns a structured `ExportResult`. Failed points are NaN-filled rather than dropped, partial model runs are surfaced via `status="partial"`, and `ExportResult.embedding(model)` provides a typed shortcut to the embedding array.
 
 ### Fixed

mkdocs.yml

@@ -45,6 +45,12 @@ markdown_extensions:
   - toc:
       permalink: true
 
+extra:
+  version:
+    provider: mike
+    default: latest
+    alias: true
+
 extra_javascript:
   - https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js
 

pyproject.toml

@@ -78,6 +78,9 @@ dev = [
   "pytest-xdist>=3.0",
   "ruff>=0.5.0",
   "pre-commit>=3.0",
+  "mkdocs-material>=9.5",
+  "pymdown-extensions>=10.0",
+  "mike>=2.1",
 ]
 
 [project.scripts]