docs: add versioned docs deployment with mike

Enable the mike version provider in zensical.toml and deploy docs to
the gh-pages branch: main pushes publish the dev version (docs.yml),
release tags publish X.Y.Z with the latest alias and root redirect
(on-release-main.yml). The zensical-compatible mike fork is pinned in
the dev dependency group and commit-hash locked in uv.lock

Author: raederan

.github/workflows/docs.yml

@@ -1,7 +1,8 @@
-# Deploys the documentation to GitHub Pages via the Pages artifact method
-# (repo setting: Pages source = "GitHub Actions").
-# NOTE: the docs-versioning phase of the migration replaces this with a
-# mike-based deploy to the gh-pages branch.
+# Deploys the documentation with mike (versioned docs on the gh-pages
+# branch; repo setting: Pages source = "Deploy from a branch: gh-pages").
+#
+# push to main        -> version "dev"
+# tag vX.Y.Z          -> version "X.Y.Z" + "latest" alias (on-release-main.yml)
 
 name: Docs
 
@@ -11,38 +12,30 @@ on:
   workflow_dispatch:
 
 permissions:
-  contents: read
-  pages: write
-  id-token: write
+  # mike commits the built site to the gh-pages branch
+  contents: write
 
 concurrency:
   group: pages
   cancel-in-progress: false
 
 jobs:
   deploy-docs:
-    environment:
-      name: github-pages
-      url: ${{ steps.deployment.outputs.page_url }}
     runs-on: ubuntu-latest
     steps:
       - name: Check out
         uses: actions/checkout@v4
         with:
-          # deep clone incl. tags so hatch-vcs can derive the version
+          # deep clone incl. tags: hatch-vcs needs them and mike needs gh-pages
           fetch-depth: 0
 
       - name: Set up the environment
         uses: ./.github/actions/setup-python-env
 
-      - name: Build documentation
-        run: uv run zensical build --clean
+      - name: Configure git identity
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
 
-      - name: Upload artifact
-        uses: actions/upload-pages-artifact@v4
-        with:
-          path: site
-
-      - name: Deploy to GitHub Pages
-        id: deployment
-        uses: actions/deploy-pages@v4
+      - name: Deploy dev documentation
+        run: uv run mike deploy --push dev

.github/workflows/on-release-main.yml

@@ -4,8 +4,8 @@
 # configured on PyPI references workflow "on-release-main.yml" and
 # environment "pypi" (no token/secret involved).
 #
-# Docs are deployed from main by docs.yml; the docs-versioning phase of
-# the migration adds the per-release docs deploy (mike) to this workflow.
+# Docs: dev builds are deployed from main by docs.yml; deploy-docs below
+# publishes the versioned per-release docs (mike -> gh-pages branch).
 
 name: release-main
 
@@ -39,3 +39,36 @@ jobs:
 
       - name: Publish package
         run: uv publish --trusted-publishing always
+
+  deploy-docs:
+    needs: publish
+    runs-on: ubuntu-latest
+    permissions:
+      # mike commits the built site to the gh-pages branch
+      contents: write
+    concurrency:
+      group: pages
+      cancel-in-progress: false
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          # deep clone incl. tags: hatch-vcs needs them and mike needs gh-pages
+          fetch-depth: 0
+
+      - name: Set up the environment
+        uses: ./.github/actions/setup-python-env
+
+      - name: Configure git identity
+        run: |
+          git config user.name 'github-actions[bot]'
+          git config user.email 'github-actions[bot]@users.noreply.github.com'
+
+      - name: Deploy versioned documentation
+        env:
+          TAG: ${{ github.ref_name }}
+        run: |
+          ver="${TAG#v}"
+          # --alias-type=copy keeps /latest/ a real directory instead of a
+          # redirect, so machine-readable files stay fetchable there
+          uv run mike deploy --push --alias-type=copy --update-aliases "$ver" latest
+          uv run mike set-default --push latest

pyproject.toml

@@ -133,6 +133,8 @@ dev = [
     # docs
     "zensical>=0.0.46",
     "mkdocstrings-python>=1.0.3",
+    # docs versioning: zensical-compatible mike fork (same pin as OO-LD/oold-schema)
+    "mike @ git+https://github.com/squidfunk/mike.git@2.2.0+zensical-0.1.0",
 ]
 
 [tool.hatch.build.targets.wheel]

uv.lock

@@ -69,6 +69,11 @@ accent = "deep orange"
 toggle.icon = "material/brightness-4"
 toggle.name = "Switch to system preference"
 
+# Docs versioning: version selector fed by mike (versions.json on the
+# gh-pages branch). main -> dev, tag vX.Y.Z -> X.Y.Z + latest alias.
+[project.extra.version]
+provider = "mike"
+
 [[project.extra.social]]
 icon = "fontawesome/brands/github"
 link = "https://github.com/OpenSemanticLab/osw-python"