Docs: Update deps and enable reproducible builds

Update sphinx version and fix resulting conf.py build errors.
(language and extra css files)

Add sphinx todo extension

Add requirements.in file to list top-level docs dependencies.

Have rtd install pip-tools and use pip-compile to always generate an
updated requirements file in the rtd build output.

Add the requirements.txt generated by pip-compile to pin this version
of the docs as a reproducible build.

Note: When wanting to pin a new docs build, copy the results of
pip-compile from the build logs and overwrite the existing
requirements.txt

.readthedocs.yaml

@@ -13,7 +13,7 @@ formats:
 build:
   os: ubuntu-22.04
   tools:
-    python: "3.11"
+    python: "3.12"
   jobs:
     post_checkout:
       # Cancel building pull requests when there aren't changed in the docs directory or YAML file.
@@ -22,6 +22,20 @@ build:
         then
           exit 183;
         fi
+    pre_install:
+      # pip-compile was used to generate the requirements.txt file to enable
+      # reproducible builds.
+      #
+      # If adding or updating top-level dependencies, update requirements.in and
+      # then overwrite existing requirements.txt with results of `pip-compile`.
+      #
+      # If simply wanting to update transitive dependencies to pin a new
+      # reproducible build, then overwrite existing requirements.txt with
+      # results of `pip-compile`.
+      #
+      # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html#pin-your-transitive-dependencies
+      - python -m pip install pip-tools
+      - pip-compile --strip-extras -o docs/new_requirements.txt docs/requirements.in --upgrade
 
 # Build documentation in the docs/ directory with Sphinx
 sphinx:
@@ -30,6 +44,8 @@ sphinx:
 
 # We recommend specifying your dependencies to enable reproducible builds:
 # https://docs.readthedocs.io/en/stable/guides/reproducible-builds.html
-# python:
-#   install:
-#   - requirements: docs/requirements.txt
+python:
+  install:
+  # If needing to update for pinning a new reproducible build, then overwrite with
+  # results of `pip-compile` command above.
+  - requirements: docs/requirements.txt

docs/conf.py

@@ -28,7 +28,7 @@
 # Add any Sphinx extension module names here, as strings. They can be
 # extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
 # ones.
-#extensions = []
+extensions = ['sphinx.ext.todo']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']
@@ -63,7 +63,7 @@
 #
 # This is also used if you do content translation via gettext catalogs.
 # Usually you set "language" from the command line for these cases.
-language = None
+language = 'en'
 
 # There are two options for replacing |today|: either, you set today to some
 # non-false value, then it is used:
@@ -139,7 +139,7 @@
 # so a file named "default.css" will overwrite the builtin "default.css".
 html_static_path = ['_static']
 
-def setup(app):   app.add_stylesheet("theme_overrides.css" )
+html_css_files = ['theme_overrides.css']
 
 # Add any extra paths that contain custom files (such as robots.txt or
 # .htaccess) here, relative to this directory. These files are copied

docs/requirements.in

@@ -0,0 +1,2 @@
+sphinx
+sphinx_rtd_theme

docs/requirements.txt

@@ -0,0 +1,65 @@
+#
+# This file is autogenerated by pip-compile with Python 3.12
+# by the following command:
+#
+#    pip-compile --output-file=docs/requirements.txt --strip-extras docs/requirements.in
+#
+alabaster==0.7.13
+    # via sphinx
+babel==2.13.1
+    # via sphinx
+certifi==2023.7.22
+    # via requests
+charset-normalizer==3.3.1
+    # via requests
+docutils==0.18.1
+    # via
+    #   sphinx
+    #   sphinx-rtd-theme
+idna==3.4
+    # via requests
+imagesize==1.4.1
+    # via sphinx
+jinja2==3.1.2
+    # via sphinx
+markupsafe==2.1.3
+    # via jinja2
+packaging==23.2
+    # via sphinx
+pygments==2.16.1
+    # via sphinx
+requests==2.31.0
+    # via sphinx
+snowballstemmer==2.2.0
+    # via sphinx
+sphinx==7.2.6
+    # via
+    #   -r docs/requirements.in
+    #   sphinx-rtd-theme
+    #   sphinxcontrib-applehelp
+    #   sphinxcontrib-devhelp
+    #   sphinxcontrib-htmlhelp
+    #   sphinxcontrib-jquery
+    #   sphinxcontrib-qthelp
+    #   sphinxcontrib-serializinghtml
+sphinx-rtd-theme==1.3.0
+    # via -r docs/requirements.in
+sphinxcontrib-applehelp==1.0.7
+    # via sphinx
+sphinxcontrib-devhelp==1.0.5
+    # via sphinx
+sphinxcontrib-htmlhelp==2.0.4
+    # via sphinx
+sphinxcontrib-jquery==4.1
+    # via sphinx-rtd-theme
+sphinxcontrib-jsmath==1.0.1
+    # via sphinx
+sphinxcontrib-qthelp==1.0.6
+    # via sphinx
+sphinxcontrib-serializinghtml==1.1.9
+    # via sphinx
+urllib3==2.0.7
+    # via requests
+
+# The following packages are considered to be unsafe in a requirements file:
+# setuptools