ci: Fix docs build in GitHub Actions (#1109)

The docs build in GitHub Actions broke with the release of jinja 3.1,
which introduced a breaking change that broke the cloud_sptheme sphinx
extension in use by our docs. That extension is not maintained any more,
so there will be no upstream fix. See also
https://foss.heptapod.net/doc-utils/cloud_sptheme/-/issues/47

That extension adds support for table styling (see
https://cloud-sptheme.readthedocs.io/en/latest/lib/cloud_sptheme.ext.table_styling.html),
but we only appear to have one table in the docs currently
(docs/source/options/segment_template_formatting.rst) and it does not
use the options added by the cloud_sptheme extension.

Therefore the best fix for GitHub Actions and any other system running
jinja 3.1 is to remove that extension from our config.

.github/workflows/build-docs.yaml

@@ -17,6 +17,12 @@ on:
         required: true
         type: string
 
+      # If true, start a debug SSH server on failures.
+      ENABLE_DEBUG:
+        required: false
+        type: boolean
+        default: false
+
 jobs:
   docs:
     name: Build docs
@@ -53,3 +59,9 @@ jobs:
           cp -a build/sphinx/html gh-pages/html
           cp -a build/doxygen/html gh-pages/docs
           cp docs/index.html gh-pages/index.html
+
+      - name: Debug
+        uses: mxschmitt/action-tmate@v3.6
+        with:
+          limit-access-to-actor: true
+        if: failure() && inputs.ENABLE_DEBUG

docs/source/conf.py

@@ -35,7 +35,6 @@ extensions = ['sphinx.ext.autodoc',
               'sphinx.ext.githubpages',
               'sphinxcontrib.plantuml',
               'recommonmark',
-              'cloud_sptheme.ext.table_styling',
               'breathe']
 
 # Breathe configurations.