docs: Implement version selector with sphinx-multiversion

.github/workflows/docs.yaml

@@ -4,6 +4,7 @@ on:
   workflow_dispatch:
   push:
     branches: ['master']
+    tags: ['v*']
 
 permissions:
   contents: read
@@ -32,7 +33,6 @@ jobs:
           enable-cache: true
       - run: |
           uv sync --group dev
-          uv build
           make docs
       - name: Upload artifact
         uses: actions/upload-pages-artifact@v3

Makefile

@@ -27,7 +27,10 @@ tox:
 
 .PHONY: docs
 docs:
-	cd ./docs && uv run $(MAKE) clean html
+	uv build
+	uv run sphinx-multiversion docs docs/_build/html
+	echo '<meta http-equiv="refresh" content="0; url=./master/index.html">' > docs/_build/html/index.html
+	touch docs/_build/html/.nojekyll
 
 .PHONY: tool
 tool:

docs/_templates/versioning.html

@@ -0,0 +1,14 @@
+{% if versions %}
+<div class="sidebar-tree">
+  <p class="caption" role="heading" aria-level="2"><span class="caption-text">VERSIONS:</span></p>
+  <div class="version-dropdown" style="margin-bottom: 1rem;">
+    <select onchange="window.location.href = this.value" style="width: 100%; padding: 0.5rem; border: 1px solid var(--color-background-border); border-radius: 0.25rem; background-color: var(--color-background-secondary); color: var(--color-foreground-primary); font-size: var(--font-size--small); cursor: pointer;">
+      {% for item in versions %}
+      <option value="{{ item.url }}" {% if item.name == current_version %}selected{% endif %}>
+        {{ item.name }}{% if item.name == current_version %} (current){% endif %}
+      </option>
+      {% endfor %}
+    </select>
+  </div>
+</div>
+{% endif %}

docs/conf.py

@@ -34,11 +34,12 @@ def get_version():
 
 extensions = [
     "sphinx.ext.autodoc",
-    "sphinx.ext.autosummary", 
+    "sphinx.ext.autosummary",
     "sphinx.ext.viewcode",
     "sphinx.ext.napoleon",
     "sphinx.ext.intersphinx",
     "sphinx.ext.githubpages",
+    "sphinx_multiversion",
 ]
 
 # Napoleon settings for Google-style docstrings
@@ -96,3 +97,32 @@ def get_version():
     "source_branch": "master",
     "source_directory": "docs/",
 }
+
+# Sidebar templates
+html_sidebars = {
+    "**": [
+        "sidebar/brand.html",
+        "sidebar/search.html",
+        "sidebar/scroll-start.html",
+        "sidebar/navigation.html",
+        "versioning.html",
+        "sidebar/scroll-end.html",
+    ]
+}
+
+# -- Sphinx-multiversion configuration ----------------------------------------
+
+# Whitelist pattern for tags (semantic versioning: vX.Y.Z)
+smv_tag_whitelist = r"^v\d+\.\d+\.\d+$"  # Match vX.Y.Z tags
+
+# Whitelist pattern for branches
+smv_branch_whitelist = r"^master$"  # Only build master branch
+
+# Whitelist pattern for remotes
+smv_remote_whitelist = r"^origin$"  # Only build from origin remote
+
+# Output all versions to the root directory
+smv_outputdir_format = "{ref.name}"
+
+# Specify the latest version (used for stable redirect)
+smv_latest_version = "master"

pyproject.toml

@@ -59,6 +59,7 @@ dev = [
     "pytest-xdist",
     "pytest-dependency",
     "sphinx",
+    "sphinx-multiversion",
     "furo",
     "types-python-dateutil",
 ]