From bbb07b5547adcd26c43bb01ce96cdea6dd5493d3 Mon Sep 17 00:00:00 2001
From: Joey Parrish <joeyparrish@users.noreply.github.com>
Date: Fri, 21 Oct 2022 11:27:58 -0700
Subject: [PATCH] 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 | 12 ++++++++++++
 docs/source/conf.py               |  1 -
 2 files changed, 12 insertions(+), 1 deletion(-)

diff --git a/.github/workflows/build-docs.yaml b/.github/workflows/build-docs.yaml
index 166698bd88..5c8084b703 100644
--- a/.github/workflows/build-docs.yaml
+++ b/.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
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 5a35ff599f..92aff35f9e 100644
--- a/docs/source/conf.py
+++ b/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.