docs: version switcher

.github/workflows/build.yml

@@ -69,28 +69,41 @@ jobs:
     - name: install dependencies
       run: |
         cd docs
-        sed -r '/tigre|astra-toolbox/d' ../scripts/requirements-test.yml > cil_environment.yml
-        conda install -c conda-forge -y conda-merge
-        conda-merge cil_environment.yml docs_environment.yml > environment.yml
+        conda install -c conda-forge -yq conda-merge
+        conda-merge <(sed -r '/tigre|astra-toolbox/d' ../scripts/requirements-test.yml) docs_environment.yml > environment.yml
         conda env update -n test
         conda list
     - name: build cil
       run: |
         mkdir build && cd build
         cmake .. -DCMAKE_BUILD_TYPE=Release -DCONDA_BUILD=ON -DCMAKE_INSTALL_PREFIX="$CONDA_PREFIX"
         cmake --build . --target install
-    - run: make -C docs dirhtml
+    - name: checkout docs
+      uses: actions/checkout@v4
+      with:
+        path: docs/build
+        ref: gh-pages
+    - name: update docs
+      run: |
+        cd docs
+        docs_dir="${{ github.ref_name }}"
+        docs_dir="${docs_dir//\//_}"
+        if test "$docs_dir" = master; then docs_dir=nightly; fi
+        rm -rf "build/$docs_dir"
+        sphinx-build -b dirhtml source "build/$docs_dir"
+        sed 's#DESTINATION#nightly#g' .redirect-template.html > build/index.html
+        ./mkversions.py
     - uses: actions/upload-artifact@v3
       with:
         name: DocumentationHTML
-        path: docs/build/dirhtml
+        path: docs/build
     - name: Push changes
       if: github.ref == 'refs/heads/master'
       uses: casperdcl/push-dir@v1
       with:
         message: Update documentation
         branch: gh-pages
-        dir: docs/build/dirhtml
+        dir: docs/build
         nojekyll: true
   docker:
     runs-on: ubuntu-latest

docs/mkversions.py

@@ -0,0 +1,27 @@
+#!/usr/bin/env python
+import json
+import re
+from pathlib import Path
+from packaging import version
+
+baseurl = "/CIL/"
+build = Path(__file__).parent / "build"
+versions = [{
+    "name": str(i.name),
+    "version": re.search(
+        "VERSION: '(.*)'",
+        (i / "_static" / "documentation_options.js").read_text(),
+        flags=re.M).group(1),
+    "url": f"{baseurl}{i.name}/"
+}
+for i in build.glob("[a-zA-Z]*") if i.is_dir()]
+
+tags = [v for v in versions if v["name"] == "v" + v["version"]]
+try:
+    stable = max(tags, key=lambda v: version.parse(v["version"]))
+except ValueError:
+    pass
+else:
+    versions += [{"name": "stable", "version": stable["version"], "url": stable["url"], "preferred": True}]
+
+(build / "versions.json").write_text(json.dumps(versions))

docs/source/conf.py

@@ -67,8 +67,8 @@
 html_theme = 'pydata_sphinx_theme'
 # default: ['localtoc.html', 'relations.html', 'sourcelink.html', 'searchbox.html']
 html_sidebars = {
-   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html'],
-   'using/windows': ['windowssidebar.html', 'searchbox.html'],
+   '**': ['globaltoc.html', 'sourcelink.html', 'searchbox.html', 'version-switcher.html'],
+   'using/windows': ['windowssidebar.html', 'searchbox.html', 'version-switcher.html'],
 }
 # Add any paths that contain custom static files (such as style sheets) here,
 # relative to this directory. They are copied after the builtin static files,
@@ -116,3 +116,10 @@
 bibtex_encoding = 'latin'
 bibtex_reference_style = 'label'
 bibtex_default_style = 'plain'
+html_theme_options = {
+    "switcher": {
+        # baseurl
+        "json_url": "/CIL/versions.json",
+        "version_match": version
+    },
+}