use again sphinx-multiversion

Author: Samoed

.github/workflows/build-docs.yaml

@@ -48,44 +48,15 @@ jobs:
           poetry install --with docs
 
       - name: Test documentation build
-        if: github.event_name == 'pull_request' && github.base_ref == 'dev'
+#        if: github.event_name == 'pull_request' && github.base_ref == 'dev'
         run: |
           echo "Testing documentation build for PR..."
-          poetry run sphinx-build docs/source docs/build/html
+          make test-docs
 
-      - name: Generate missing tags list
-#        if: github.event_name == 'push' || github.event_name == 'release'
-        id: missing_tags
+      - name: build multiversion documentation
+        # if: ${{ github.ref == 'refs/heads/dev' }}
         run: |
-          # Fetch existing documentation versions from gh-pages
-          mkdir -p existing_versions
-          git fetch origin gh-pages --depth=1
-          git checkout origin/gh-pages -- versions || true
-          
-          # List existing tags and built versions
-          EXISTING_VERSIONS=$(ls versions | tr '\n' ' ')
-          ALL_TAGS=$(git tag --list "v*" | tr '\n' ' ')
-          
-          # Find missing tags
-          MISSING_TAGS=""
-          for TAG in $ALL_TAGS; do
-            if [[ ! " $EXISTING_VERSIONS " =~ " $TAG " ]]; then
-              MISSING_TAGS+="$TAG "
-            fi
-          done
-          
-          echo "Missing tags: $MISSING_TAGS"
-          echo "missing_tags=${MISSING_TAGS}" >> $GITHUB_ENV
-
-      - name: Build documentation for missing tags
-        if: env.missing_tags != ''
-        run: |
-          for TAG in ${{ env.missing_tags }}; do
-            echo "Building docs for $TAG..."
-            git checkout $TAG
-            mkdir -p docs/build/versions/$TAG
-            poetry run sphinx-build docs/source docs/build/versions/$TAG
-          done
+          make multi-version-docs
 
       - name: Build documentation for dev branch
         # if: github.ref == 'refs/heads/dev'
@@ -101,36 +72,3 @@ jobs:
           publish_dir: docs/build/versions
           destination_dir: versions
           keep_files: true
-
-  update-static:
-    name: Update Static Files in Old Releases
-    runs-on: ubuntu-latest
-    needs: build-docs
-
-    steps:
-      - name: Checkout gh-pages branch
-        uses: actions/checkout@v4
-        with:
-          ref: gh-pages
-          fetch-depth: 0
-
-      - name: Update _static in all versions
-        run: |
-          # Define path to the updated _static directory
-          UPDATED_STATIC_DIR=versions/dev/_static
-          TARGET_STATIC_DIRS=$(find versions/ -type d -name "_static")
-          
-          # Copy updated _static to all versions
-          for DIR in $TARGET_STATIC_DIRS; do
-            echo "Updating $DIR..."
-            cp -r ${UPDATED_STATIC_DIR}/* ${DIR}/ || true
-          done
-
-      - name: Commit and push changes
-        run: |
-          git add .
-          git commit -m "Update _static files in all documentation versions" || echo "No changes to commit"
-          git push
-        # with:
-        #   github_token: ${{ github.token }}
-

Makefile

@@ -31,13 +31,17 @@ docs:
 	$(poetry) python -m sphinx build -b html docs/source docs/build/html
 
 .PHONY: test-docs
-test-docs: docs
+test-docs:
 	$(poetry) python -m sphinx build -b doctest docs/source docs/build/html
 
 .PHONY: serve-docs
 serve-docs: docs
 	$(poetry) python -m http.server -d docs/build/html 8333
 
+.PHONY: multi-version-docs
+multi-version-docs:
+	$(poetry) sphinx-multiversion docs/source docs/build/html
+
 .PHONY: clean-docs
 clean-docs:
 	rm -rf docs/build

docs/source/conf.py

@@ -46,6 +46,7 @@
     "sphinx_copybutton",
     "nbsphinx",
     "sphinx.ext.intersphinx",
+    "sphinx_multiversion",
 ]
 
 templates_path = ["_templates"]
@@ -144,6 +145,19 @@
 
 mathjax_path = "https://cdn.jsdelivr.net/npm/mathjax@3/es5/tex-mml-chtml.js"
 
+# sphinx_multiversion
+# Whitelist for tags matching v1.0.0, v2.1.0 format
+smv_tag_whitelist = r'^v\d+\.\d+\.\d+$'
+
+# Whitelist for the dev branch
+smv_branch_whitelist = r'^dev$'
+
+# Output format (keeping your current format)
+smv_outputdir_format = 'versions/{config.version}'
+
+# Include both tags and dev branch as released
+smv_released_pattern = r'^(refs/tags/.*|refs/heads/dev)$'
+
 repo_root = os.path.abspath(os.path.join(os.path.dirname(__file__), '..', ".."))  # if conf.py is in docs/
 def setup(app) -> None:  # noqa: ANN001
     generate_versions_json(app, repo_root, BASE_URL)

pyproject.toml

@@ -95,6 +95,7 @@ sphinx-autodoc-typehints = "^2.5.0"
 sphinx-copybutton = "^0.5.2"
 sphinx-autoapi = "^3.3.3"
 ipykernel = "^6.29.5"
+sphinx-multiversion = "^0.2.4"
 
 [tool.poetry.scripts]
 "autointent" = "autointent._pipeline._cli_endpoint:optimize"