Update docs Pages workflow to publish on releases with latest-tag default

.github/workflows/docs2pages.yml

@@ -3,6 +3,8 @@ on:
   push:
     branches:
       - main
+  release:
+    types: [published]
   workflow_dispatch:
 
 # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages
@@ -54,7 +56,24 @@ jobs:
       run: uv sync --dev --group docs --no-group apple-silicon
     - name: Build documentation
       run: |
-        uv run sphinx-build -b html docs/ ./_site      
+        uv run sphinx-multiversion docs/ ./_site
+
+    - name: Select default docs version for site root
+      shell: bash
+      run: |
+        set -euo pipefail
+        latest_tag_dir="$(find ./_site -maxdepth 1 -mindepth 1 -type d -name 'v*' | sort -V | tail -n 1 || true)"
+
+        if [[ -n "${latest_tag_dir}" ]]; then
+          echo "Using latest released docs as default: ${latest_tag_dir}"
+          cp -a "${latest_tag_dir}/." ./_site/
+        elif [[ -d ./_site/main ]]; then
+          echo "No release tags found; falling back to main docs for root index"
+          cp -a ./_site/main/. ./_site/
+        else
+          echo "No eligible docs directory found to publish at site root" >&2
+          exit 1
+        fi
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3
 

docs/_templates/sidebar/scroll-end.html

@@ -0,0 +1,22 @@
+{%- set _versions = versions | default([]) -%}
+{%- set _current = current_version | default({'name': version}) -%}
+
+{%- if _versions %}
+<div class="sidebar-tree">
+  <p class="caption" role="heading">
+    <span class="caption-text">Version</span>
+  </p>
+  <label for="version-selector" class="visually-hidden">Version</label>
+  <select
+    id="version-selector"
+    onchange="if (this.value) window.location.href = this.value;"
+    style="width: 100%;"
+  >
+    {%- for item in _versions %}
+    <option value="{{ item.url }}" {% if item.name == _current.name %}selected{% endif %}>
+      {{ item.name }}
+    </option>
+    {%- endfor %}
+  </select>
+</div>
+{%- endif %}

docs/conf.py

@@ -33,6 +33,7 @@
     "myst_parser",
     "nbsphinx",
     "sphinx_copybutton",
+    "sphinx_multiversion",
 ]
 
 nbsphinx_allow_errors = True  # Continue through errors in notebook cells
@@ -47,6 +48,12 @@
 
 autodoc_mock_imports = ["modcma"]
 
+# sphinx-multiversion configuration
+smv_tag_whitelist = r"^v\d+\.\d+\.\d+$"
+smv_branch_whitelist = r"^main$"
+smv_released_pattern = r"^refs/tags/v\d+\.\d+\.\d+$"
+smv_outputdir_format = "{ref.name}"
+
 # -- Options for HTML output -------------------------------------------------
 
 # The theme to use for HTML and HTML Help pages.  See the documentation for

pyproject.toml

@@ -59,6 +59,7 @@ docs = [
     "furo>=2024.8.6,<2025",
     "sphinxext-opengraph>=0.9.1,<0.10",
     "sphinx-copybutton>=0.5.2,<0.6",
+    "sphinx-multiversion>=0.2.4,<0.3",
 ]
 methods = [
     "eoh",