Use the module sphinx-versioned-docs

Use the Python module sphinx-versioned-docs to get versioned docs.
Currently, there is only a version for the HEAD of the master branch
but release versions can be added later by specifying a release tag.

.github/workflows/python_sphinx_docs.yml

@@ -18,7 +18,9 @@ jobs:
       runs-on: ubuntu-latest
       steps:
         - name: checkout source code
-          uses: actions/checkout@v3
+          uses: actions/checkout@v4
+          with:
+            fetch-depth: 0   # Fetch all history for all tags and branches
         - name: Set up Python
           uses: actions/setup-python@v4
           with:
@@ -34,12 +36,15 @@ jobs:
             cd python
             mkdir gh-pages
             touch gh-pages/.nojekyll
-            cd sphinx_docs/docs/
-            poetry run sphinx-build -b html . _build
+            cd sphinx_docs
+            # Currently we build only docs for the HEAD of the master branch
+            # Later we can add release tags to the list to get the docs for the releases
+            # For example: -b "main, release/2024.04/final" will build the docs for
+            # the main branch and the release/2024.04/final tag
+            poetry run sphinx-versioned -m master -b master --git-root ../../
         - name: Copy documentation to gh-pages
           run: |
-            cd python/sphinx_docs/docs
-            cp -r _build/* ../../gh-pages/
+            cp -r python/sphinx_docs/docs/_build/* gh-pages/
         - name: Deploy documentation
           if: ${{ github.event_name == 'push' }}
           uses: JamesIves/github-pages-deploy-action@v4

python/sphinx_docs/Makefile

@@ -0,0 +1,7 @@
+.PHONY: docs
+
+# Build the documentation locally for the current branch
+# NOTE: You need to commit your changes before running this command
+docs:
+	@CURRENT_BRANCH=$(shell git rev-parse --abbrev-ref HEAD)
+	sphinx-versioned -m $$CURRENT_BRANCH -b $$CURRENT_BRANCH --git-root ../../

python/sphinx_docs/pyproject.toml

@@ -14,6 +14,7 @@ python = "^3.10"
 sphinx = "^7.2.5"
 sphinx-rtd-theme = "^1.3.0"
 click = "^8.1.7"
+sphinx-versioned-docs = "^1.3.1"
 
 [build-system]
 requires = ["poetry-core"]