From cd566873f29c1af5536d1fd48b02c8ba90a2cccd Mon Sep 17 00:00:00 2001
From: Brian Neradt <brian.neradt@gmail.com>
Date: Wed, 18 Jan 2023 21:08:10 +0000
Subject: [PATCH] Update rtd-theme to the latest version

This updates our docs to use the latest rtd-theme and updates our
conf.py to handle our custom css file in a way that now works with the
latest Sphinx release. (Overriding html_context:css_files now removes
the theme's css files instead of adding to them.)
---
 doc/Pipfile |  8 ++++++--
 doc/conf.py | 22 ++++++----------------
 2 files changed, 12 insertions(+), 18 deletions(-)

diff --git a/doc/Pipfile b/doc/Pipfile
index 53b2d87badf..ba2b3f17f37 100644
--- a/doc/Pipfile
+++ b/doc/Pipfile
@@ -23,9 +23,13 @@ verify_ssl = true
 
 [packages]
 
-sphinx = ">=6.x"
+# We pin Sphinx because the sphinx-rtd-theme suggests this as a best practice.
+# If not, we will often face issues when Sphinx updates their version before
+# sphinx-rtd-theme has had time to update their component for the new sphinx
+# version.
+sphinx = "==6.1.3"
 
-sphinx-rtd-theme = "*"
+sphinx-rtd-theme = ">=1.*"
 sphinxcontrib-jquery = "*"
 sphinxcontrib-plantuml = "*"
 # i18n
diff --git a/doc/conf.py b/doc/conf.py
index ea731db3f29..89f417af1fc 100644
--- a/doc/conf.py
+++ b/doc/conf.py
@@ -49,8 +49,14 @@
 sys.path.insert(0, os.path.abspath('ext'))
 sys.path.insert(0, os.path.abspath('.'))
 
+
+# Allow for us to add our override CSS file (new with Sphinx 1.x)
+def setup(app):
+    app.add_css_file('override.css')
+
 # -- General configuration -----------------------------------------------------
 
+
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
 extensions = [
@@ -281,22 +287,6 @@ def issue_reference(self, match, lineno):
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['static']
 
-# Include a stylesheet that overrides default table styling, to provide
-# content wrapping.
-html_context = {
-    'css_files': [
-        '_static/override.css'
-    ]
-}
-if os.environ.get('READTHEDOCS', None) == 'True':
-    html_context = {
-        'css_files': [
-            'https://media.readthedocs.org/css/sphinx_rtd_theme.css',
-            'https://media.readthedocs.org/css/readthedocs-doc-embed.css',
-            '_static/override.css'
-        ]
-    }
-
 # If not '', a 'Last updated on:' timestamp is inserted at every page bottom,
 # using the given strftime format.
 #html_last_updated_fmt = '%b %d, %Y'