[wip] Attempt sphinx-multiversion

.github/workflows/docs.yml

@@ -29,6 +29,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,7 +45,7 @@ jobs:
           export ROOT_INCLUDE_PATH=$(pwd)/install/include
 
           echo -e "::endgroup::\n::group::build doc"
-          sphinx-build -M html doc doc_output
+          sphinx-multiversion doc doc_output
 
     - name: Upload artifact
       uses: actions/upload-pages-artifact@v3

doc/conf.py

@@ -48,12 +48,13 @@
     "sphinx.ext.napoleon",
     "myst_parser",
     "breathe",
+    "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 +152,9 @@
     )
 
 print("Done with python API doc generation")
+
+# -- multiversion setup -------------------------------------------------------
+smv_tag_whitelist = r'^(v[0-9]{2}-[0-9]{2}(-[0-9]{2})?)$'
+smv_remote_whitelist = r'^(upstream)$'
+smv_branch_whitelist = r'^master$'
+smv_released_pattern = r'^tags/.*$'