Use sphinx-multiversion for generating versioned docs

Adapt the github actions workflow to populate a few template like things during the publish step, so that the generated documentation always points to either the latest tag (lexicographic sorting) or to the github ref that has just been generated
AIDASoft · Dec 21, 2023 · 933d9d7 · 933d9d7
1 parent da36b57
commit 933d9d7
Show file tree

Hide file tree

Showing 5 changed files with 73 additions and 47 deletions.
diff --git a/.github/workflows/docs.yml b/.github/workflows/docs.yml
@@ -19,7 +19,8 @@ jobs:
 
     steps:
     - uses: actions/checkout@v4
-    - uses: actions/configure-pages@v4
+      with:
+        fetch-depth: 0  # Need to full repo for getting all tags
     - uses: cvmfs-contrib/github-action-cvmfs@v3
     - uses: aidasoft/run-lcg-view@v4
       with:
@@ -29,6 +30,10 @@ jobs:
           echo "::group::Install dependencies"
           python3 -m pip install -r doc/requirements.txt
           export PATH=/root/.local/bin:$PATH
+          # Newer versions of git are more cautious around the github runner
+          # environment and without this git rev-parse --show-cdup in pre-commit
+          # fails
+          git config --global --add safe.directory $(pwd)
 
           echo -e "::endgroup::\n::group::Build podio"
           cmake -B build . --install-prefix=$(pwd)/install \
@@ -41,41 +46,55 @@ jobs:
           export ROOT_INCLUDE_PATH=$(pwd)/install/include
 
           echo -e "::endgroup::\n::group::build doc"
-          sphinx-build -M html doc doc_output
+          export GIT_CURRENT_REF=${{ github.ref_name }}
+          # sphinx-build -M html doc doc_output
+          sphinx-multiversion doc doc_output
+
+          cp doc/aux/main_index_redirect.html doc_output/index.html
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3
       with:
-        path: doc_output/html
+        path: doc_output
 
   publish-doc:
     needs: build-doc
     runs-on: ubuntu-latest
 
     steps:
-      - uses: actions/checkout@v4
-        with:
-          ref: gh-pages
       - uses: actions/download-artifact@v4
         with:
           name: github-pages
           path: doc_artifact
 
       - name: Update documentation
-        env:
-          TARGET_DIR: ${{ github.ref_name }}
         run: |
-          mkdir -p ${TARGET_DIR}
-          rm -rf ${TARGET_DIR}/*
-          tar -xvf doc_artifact/artifact.tar --directory ${TARGET_DIR}
+          tar -xvf doc_artifact/artifact.tar --directory .
           rm -r doc_artifact
+          # If there are tags simply use the latest one via lexicographic sort
+          if ls -d v*/ > /dev/null 2>&1; then
+            latest_version=$(ls -d v*/ | tail -n1)
+            sed -i s'/__LATEST__/'"${latest_version%/}"'/g' index.html
+          else
+            # Fall back to whatever we just built now
+            sed -i s'/__LATEST__/${{ github.ref_name }}/g' index.html
+          fi
 
       - name: Commit and push changes
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
-          TARGET_DIR: ${{ github.ref_name }}
         run: |
+          git init
           git config --global user.email ${GITHUB_ACTOR_ID}+${GITHUB_ACTOR}@users.noreply.github.com
           git config --global user.name ${GITHUB_ACTOR}
-          git add ${TARGET_DIR}
-          git diff-index --quiet HEAD 2>&1 > /dev/null || git commit -m "Update documentation for ${TARGET_DIR}" && git push
+          git remote add upstream https://${GITHUB_ACTOR}:${GITHUB_TOKEN}@github.com/${GITHUB_REPOSITORY}.git
+
+          git checkout -b gh-pages
+
+          touch .nojekyll
+          git add .nojekyll
+          git commit -m "Add .nojekyll for ${GITHUB_SHA}"
+
+          git add -A .
+          git commit -m "Rebuild page at ${GITHUB_SHA}"
+          git push -f upstream gh-pages:gh-pages
diff --git a/.readthedocs.yml b/.readthedocs.yml
diff --git a/doc/_templates/versions.html b/doc/_templates/versions.html
@@ -0,0 +1,22 @@
+{% if current_version %}
+<div class="rst-versions" data-toggle="rst-versions" role="note" aria-label="versions">
+  <span class="rst-current-version" data-toggle="rst-current-version">
+    <span class="fa fa-book"> Other Versions</span>
+    v: {{ current_version.name }}
+    <span class="fa fa-caret-down"></span>
+  </span>
+  <div class="rst-other-versions">
+    {%- if versions.tags or versions.branches -%}
+    <dl>
+      <dt>Versions</dt>
+      {%- for version in versions.branches %}
+      <dd><a href="{{ version.url }}">{{ version.name }}</a></dd>
+      {%- endfor %}
+      {%- for version in versions.tags %}
+      <dd><a href="{{ version.url }}">{{ version.name }}</a></dd>
+      {%- endfor %}
+    </dl>
+    {%- endif -%}
+  </div>
+</div>
+{% endif %}
diff --git a/doc/aux/main_index_redirect.html b/doc/aux/main_index_redirect.html
@@ -0,0 +1,9 @@
+<!DOCTYPE html>
+<html>
+  <head>
+    <title>Redirecting to latest release</title>
+    <meta charset="utf-8">
+    <meta http-equiv="refresh" content="0; url=./__LATEST__/index.html">
+    <link rel="canonical" href="https://tmadlener.github.io/podio/__LATEST__/index.html">
+  </head>
+</html>
diff --git a/doc/conf.py b/doc/conf.py
@@ -48,12 +48,14 @@
     "sphinx.ext.napoleon",
     "myst_parser",
     "breathe",
+    "sphinx_copybutton",
+    "sphinx_multiversion",
     ]
 
 source_suffix = {".rst": "restructuredtext", ".md": "markdown"}
 
 # Add any paths that contain templates here, relative to this directory.
-# templates_path = ["_templates"]
+templates_path = ["_templates"]
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
@@ -151,3 +153,9 @@
     )
 
 print("Done with python API doc generation")
+
+# -- multiversion setup -------------------------------------------------------
+mv_tag_whitelist = r'^v[0-9]{2}-[0-9]{2}(-[0-9]{2})?$'
+smv_remote_whitelist = r'^(origin)$'
+smv_branch_whitelist = r'^(master|docs-on-gh-pages)$'
+smv_released_pattern = r'^tags/.*$'