Enhance documentation build process and add version switcher for improved navigation

CSSFrancis · CSSFrancis · commit c4d7fb7d411d · 2026-03-16T18:05:12.000-05:00
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -45,13 +45,6 @@ jobs:
       - name: Install dependencies (with docs extras)
         run: uv sync --extra docs
 
-      # ── Sphinx build ───────────────────────────────────────────────────────
-      # -W turns warnings into errors so broken cross-references are caught.
-      # Remove -W if the gallery examples produce unavoidable warnings.
-      - name: Build HTML documentation
-        run: |
-          uv run sphinx-build -b html docs build/html -W --keep-going
-
       # ── Determine deployment target ─────────────────────────────────────────
       # Release tag  (refs/tags/v1.2.3) → destination = "v1.2.3"
       # Everything else (push to main, manual dispatch) → destination = "dev"
@@ -65,6 +58,15 @@ jobs:
             echo "dest_dir=dev" >> "$GITHUB_OUTPUT"
           fi
 
+      # ── Sphinx build ───────────────────────────────────────────────────────
+      # -W turns warnings into errors so broken cross-references are caught.
+      # Remove -W if the gallery examples produce unavoidable warnings.
+      - name: Build HTML documentation
+        env:
+          DOCS_VERSION: ${{ steps.target.outputs.dest_dir }}
+        run: |
+          uv run sphinx-build -b html docs build/html -W --keep-going
+
       # ── Deploy to gh-pages ────────────────────────────────────────────────
       # keep_files: true preserves all existing directories on the branch so
       # versioned releases accumulate rather than overwriting each other.
@@ -80,3 +82,16 @@ jobs:
           commit_message: |
             docs: deploy ${{ steps.target.outputs.dest_dir }} @ ${{ github.sha }}
 
+      # ── Deploy root files (redirect + switcher) ────────────────────────────
+      # Places index.html and switcher.json at the root of gh-pages so the
+      # bare URL redirects to dev/ and the version switcher is always reachable.
+      - name: Deploy root redirect and switcher
+        uses: peaceiris/actions-gh-pages@v4
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./docs/_root
+          destination_dir: .
+          keep_files: true
+          commit_message: |
+            docs: update root redirect and switcher.json @ ${{ github.sha }}
+
diff --git a/docs/_root/index.html b/docs/_root/index.html
@@ -0,0 +1,16 @@
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <title>anyplotlib – redirecting…</title>
+    <!-- Redirect to the latest dev docs. -->
+    <meta http-equiv="refresh" content="0; url=dev/" />
+    <link rel="canonical" href="dev/" />
+  </head>
+  <body>
+    <p>
+      Redirecting to <a href="dev/">dev documentation</a>…
+    </p>
+  </body>
+</html>
+
diff --git a/docs/_root/switcher.json b/docs/_root/switcher.json
@@ -0,0 +1,8 @@
+[
+  {
+    "name": "dev (latest)",
+    "version": "dev",
+    "url": "https://cssfrancis.github.io/anyplotlib/dev/"
+  },
+]
+
diff --git a/docs/conf.py b/docs/conf.py
@@ -19,6 +19,12 @@
 author = "anyplotlib contributors"
 release = "0.1.0"
 
+# When built in CI the workflow sets DOCS_VERSION to the tag name (e.g.
+# "v0.1.0") or "dev".  Fall back to "dev" for local builds.
+_docs_version = os.environ.get("DOCS_VERSION", "dev")
+_base = "https://cssfrancis.github.io/anyplotlib/"
+html_baseurl = f"{_base}{_docs_version}/"
+
 # -- General configuration ---------------------------------------------------
 extensions = [
     "sphinx.ext.autodoc",
@@ -76,13 +82,17 @@
 html_static_path = ["_static"]
 
 html_theme_options = {
-    "github_url": "https://github.com/",
+    "github_url": "https://github.com/CSSFrancis/anyplotlib",
     "logo": {
         "image_light": "_static/anyplotlib.svg",
         "image_dark": "_static/anyplotlib.svg",
         "text": "anyplotlib",
     },
-    "navbar_end": ["navbar-icon-links"],
+    "switcher": {
+        "json_url": f"{_base}switcher.json",
+        "version_match": _docs_version,
+    },
+    "navbar_end": ["version-switcher", "navbar-icon-links"],
     "show_toc_level": 2,
 }
 
