135 refactor docs migrate mkdocs to zensical

.github/workflows/docs-backfill.yml

@@ -0,0 +1,155 @@
+name: Backfill Documentation Versions
+
+on:
+  workflow_dispatch:
+    inputs:
+      include_dev:
+        description: "Also publish the current master branch as dev"
+        required: true
+        type: boolean
+        default: true
+      wipe_existing:
+        description: "Clear the current gh-pages contents before backfilling"
+        required: true
+        type: boolean
+        default: false
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  backfill:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Ubuntu dependencies
+        run: sudo apt-get install graphviz pandoc
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-3.12-${{ hashFiles('**/uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-3.12-
+            uv-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: |
+          uv sync --all-extras
+          uv pip install \
+            "mkdocs>=1.6.0" \
+            "mkdocs-autorefs>=1.4.3" \
+            "mkdocs-awesome-pages-plugin>=2.10.1" \
+            "mkdocs-gen-files>=0.5.0" \
+            "mkdocs-jupyter>=0.25.1" \
+            "mkdocs-literate-nav>=0.6.2" \
+            "mkdocs-material>=9.6.16" \
+            "mkdocstrings[python]>=0.19.0"
+
+      - name: Prepare gh-pages worktree
+        run: |
+          if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+            git fetch origin gh-pages --depth=1
+            git worktree add --force -B gh-pages .publish-site origin/gh-pages
+          else
+            origin_url=$(git remote get-url origin)
+            mkdir .publish-site
+            git init .publish-site
+            git -C .publish-site remote add origin "$origin_url"
+            git -C .publish-site checkout --orphan gh-pages
+          fi
+          git -C .publish-site config user.name "github-actions[bot]"
+          git -C .publish-site config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+          if [[ "${{ inputs.wipe_existing }}" == "true" ]]; then
+            find .publish-site -mindepth 1 -maxdepth 1 ! -name .git -exec rm -rf {} +
+          fi
+
+      - name: Backfill tagged versions
+        run: |
+          latest_tag=$(git tag --list 'v*' --sort=-version:refname | head -n 1)
+          mapfile -t tags < <(git tag --list 'v*' --sort=version:refname)
+          mkdir -p .backfill-worktrees
+          failed_tags=()
+
+          for tag in "${tags[@]}"; do
+            worktree_dir=".backfill-worktrees/${tag}"
+            git worktree add --force "$worktree_dir" "$tag"
+
+            if ! (
+              cd "$worktree_dir"
+              uv sync --all-extras || uv pip install -e .
+              MIKE_DOCS_VERSION="$tag" bash "$GITHUB_WORKSPACE/docs/scripts/build_docs.sh" "$PWD"
+              args=(
+                --source-dir "$PWD/site"
+                --target-dir "$GITHUB_WORKSPACE/.publish-site"
+                --version "$tag"
+                --title "$tag"
+              )
+              if [[ "$tag" == "$latest_tag" ]]; then
+                args+=(--alias latest --default latest)
+              fi
+              uv run python "$GITHUB_WORKSPACE/docs/scripts/publish_versioned_site.py" "${args[@]}"
+            ); then
+              failed_tags+=("$tag")
+            fi
+
+            git worktree remove --force "$worktree_dir"
+          done
+
+          if [[ "${{ inputs.include_dev }}" == "true" ]]; then
+            MIKE_DOCS_VERSION=dev bash docs/scripts/build_docs.sh
+            uv run python docs/scripts/publish_versioned_site.py \
+              --source-dir site \
+              --target-dir .publish-site \
+              --version dev \
+              --title dev
+          fi
+
+          if (( ${#failed_tags[@]} > 0 )); then
+            printf 'Failed tags: %s\n' "${failed_tags[*]}" >&2
+            exit 1
+          fi
+
+      - name: Commit gh-pages update
+        run: |
+          git -C .publish-site add -A
+          if git -C .publish-site diff --cached --quiet; then
+            echo "No documentation changes to publish."
+            exit 0
+          fi
+
+          git -C .publish-site commit -m "docs: backfill versioned site"
+          git -C .publish-site push origin gh-pages
+
+      - name: Prepare Pages artifact
+        run: |
+          rm -rf .pages-site
+          mkdir -p .pages-site
+          cp -R .publish-site/. .pages-site/
+          rm -rf .pages-site/.git
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: .pages-site
+
+      - uses: actions/deploy-pages@v4
+        id: deployment

.github/workflows/docs.yml

@@ -0,0 +1,134 @@
+name: Documentation Site
+
+on:
+  push:
+    branches:
+      - master
+    tags:
+      - "v*"
+
+concurrency:
+  group: docs-${{ github.ref }}
+  cancel-in-progress: false
+
+permissions:
+  contents: write
+  pages: write
+  id-token: write
+
+jobs:
+  deploy:
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/configure-pages@v5
+
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Ubuntu dependencies
+        run: sudo apt-get install graphviz pandoc
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+        with:
+          version: "latest"
+
+      - name: Set up Python
+        run: uv python install 3.12
+
+      - name: Cache uv dependencies
+        uses: actions/cache@v4
+        with:
+          path: ~/.cache/uv
+          key: uv-${{ runner.os }}-3.12-${{ hashFiles('**/uv.lock') }}
+          restore-keys: |
+            uv-${{ runner.os }}-3.12-
+            uv-${{ runner.os }}-
+
+      - name: Install dependencies
+        run: uv sync --all-extras
+
+      - name: Determine docs target
+        id: target
+        run: |
+          if [[ "${GITHUB_REF_TYPE}" == "tag" ]]; then
+            echo "version=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+            echo "title=${GITHUB_REF_NAME}" >> "$GITHUB_OUTPUT"
+            echo "alias=latest" >> "$GITHUB_OUTPUT"
+            echo "default=latest" >> "$GITHUB_OUTPUT"
+          else
+            echo "version=dev" >> "$GITHUB_OUTPUT"
+            echo "title=dev" >> "$GITHUB_OUTPUT"
+            echo "alias=" >> "$GITHUB_OUTPUT"
+            echo "default=" >> "$GITHUB_OUTPUT"
+          fi
+
+      - name: Prepare gh-pages worktree
+        run: |
+          if git ls-remote --exit-code --heads origin gh-pages >/dev/null 2>&1; then
+            git fetch origin gh-pages --depth=1
+            git worktree add --force -B gh-pages .publish-site origin/gh-pages
+          else
+            origin_url=$(git remote get-url origin)
+            mkdir .publish-site
+            git init .publish-site
+            git -C .publish-site remote add origin "$origin_url"
+            git -C .publish-site checkout --orphan gh-pages
+          fi
+
+      - name: Configure gh-pages author
+        run: |
+          git -C .publish-site config user.name "github-actions[bot]"
+          git -C .publish-site config user.email "41898282+github-actions[bot]@users.noreply.github.com"
+
+      - name: Build docs
+        env:
+          MIKE_DOCS_VERSION: ${{ steps.target.outputs.version }}
+        run: bash docs/scripts/build_docs.sh
+
+      - name: Publish versioned site
+        run: |
+          args=(
+            --source-dir site
+            --target-dir .publish-site
+            --version "${{ steps.target.outputs.version }}"
+            --title "${{ steps.target.outputs.title }}"
+          )
+
+          if [[ -n "${{ steps.target.outputs.alias }}" ]]; then
+            args+=(--alias "${{ steps.target.outputs.alias }}")
+          fi
+          if [[ -n "${{ steps.target.outputs.default }}" ]]; then
+            args+=(--default "${{ steps.target.outputs.default }}")
+          fi
+
+          uv run python docs/scripts/publish_versioned_site.py "${args[@]}"
+
+      - name: Commit gh-pages update
+        run: |
+          git -C .publish-site add -A
+          if git -C .publish-site diff --cached --quiet; then
+            echo "No documentation changes to publish."
+            exit 0
+          fi
+
+          git -C .publish-site commit -m "docs: publish ${{ steps.target.outputs.version }}"
+          git -C .publish-site push origin gh-pages
+
+      - name: Prepare Pages artifact
+        run: |
+          rm -rf .pages-site
+          mkdir -p .pages-site
+          cp -R .publish-site/. .pages-site/
+          rm -rf .pages-site/.git
+
+      - uses: actions/upload-pages-artifact@v4
+        with:
+          path: .pages-site
+
+      - uses: actions/deploy-pages@v4
+        id: deployment

.gitignore

@@ -288,4 +288,9 @@ cython_debug/
 # End of https://www.toptal.com/developers/gitignore/api/visualstudiocode,pycharm,jupyternotebooks,python
 !/build/
 /IncrementalTorch.egg-info/
-docs/benchmarks/index.md
+docs/benchmarks/*/
+docs/examples/index.md
+docs/examples/*/index.md
+docs/reference/**
+!docs/reference/index.md
+docs/generated/**