fix(docs): use sphinx-multiversion-contrib for Sphinx 7+ compatibility

bsbodden · bsbodden · commit de976a387e48 · 2026-03-11T15:26:38.000-07:00
The original sphinx-multiversion package (0.2.4) is incompatible with
Sphinx 7+ due to a changed Config.read() signature. Switch to the
maintained sphinx-multiversion-contrib fork which fixes this.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -55,7 +55,7 @@ jobs:
       - name: Create root redirect
         run: |
           # Find the latest tag that matches our whitelist, fall back to main
-          LATEST_TAG=$(git tag --sort=-v:refname | grep -E '^v0\.([4-9]|[0-9]{2,})\.[0-9]+$|^v[1-9][0-9]*\.[0-9]+\.[0-9]+$' | head -1)
+          LATEST_TAG=$(git tag --sort=-v:refname | grep -E '^v0\.4\.([1-9][0-9]*)$|^v0\.([5-9]|[0-9]{2,})\.[0-9]+$|^v[1-9][0-9]*\.[0-9]+\.[0-9]+$' | head -1)
           TARGET="${LATEST_TAG:-main}"
           cat > docs/_build/html/index.html << 'REDIRECT_EOF'
           <!DOCTYPE html>
diff --git a/docs/conf.py b/docs/conf.py
@@ -101,8 +101,8 @@
 ]
 
 # -- sphinx-multiversion options ---------------------------------------------
-# Tag whitelist: match v0.4.0+ and v1.0.0+ (skip old tags without docs/)
-smv_tag_whitelist = r"^v0\.(([4-9]|\d{2,})\.\d+)$|^v([1-9]\d*)\.\d+\.\d+$"
+# Tag whitelist: match v0.4.1+ and v1.0.0+ (v0.4.0 and earlier lack docs/)
+smv_tag_whitelist = r"^v0\.4\.([1-9]\d*)$|^v0\.([5-9]|\d{2,})\.\d+$|^v([1-9]\d*)\.\d+\.\d+$"
 smv_branch_whitelist = r"^main$"
 smv_remote_whitelist = r"^origin$"
 smv_released_pattern = r"^refs/tags/.*$"
diff --git a/docs/requirements.txt b/docs/requirements.txt
@@ -4,5 +4,5 @@ myst-nb>=1.0
 sphinx-design>=0.5
 sphinx-copybutton>=0.5
 sphinx-favicon>=1.0
-sphinx-multiversion>=0.2.4
+sphinx-multiversion-contrib>=0.2.13
 pyyaml>=6.0
