GH-125722: Increase minimum supported Sphinx to 8.1.3

.github/workflows/reusable-docs.yml

@@ -88,7 +88,7 @@ jobs:
     - name: 'Set up Python'
       uses: actions/setup-python@v5
       with:
-        python-version: '3.13'  # known to work with Sphinx 7.2.6
+        python-version: '3.13'  # known to work with Sphinx 8.1.3
         cache: 'pip'
         cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
     - name: 'Install build dependencies'

Doc/conf.py

@@ -9,9 +9,6 @@
 import importlib
 import os
 import sys
-import time
-
-import sphinx
 
 # Make our custom extensions available to Sphinx
 sys.path.append(os.path.abspath('tools/extensions'))
@@ -97,7 +94,7 @@
 highlight_language = 'python3'
 
 # Minimum version of sphinx required
-needs_sphinx = '7.2.6'
+needs_sphinx = '8.1.3'
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.
@@ -376,13 +373,7 @@
 
 # This 'Last updated on:' timestamp is inserted at the bottom of every page.
 html_last_updated_fmt = '%b %d, %Y (%H:%M UTC)'
-if sphinx.version_info[:2] >= (8, 1):
-    html_last_updated_use_utc = True
-else:
-    html_time = int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
-    html_last_updated_fmt = time.strftime(
-        html_last_updated_fmt, time.gmtime(html_time)
-    )
+html_last_updated_use_utc = True
 
 # Path to find HTML templates to override theme
 templates_path = ['tools/templates']
@@ -619,16 +610,6 @@
 }
 extlinks_detect_hardcoded_links = True
 
-if sphinx.version_info[:2] < (8, 1):
-    # Sphinx 8.1 has in-built CVE and CWE roles.
-    extlinks |= {
-        "cve": (
-            "https://www.cve.org/CVERecord?id=CVE-%s",
-            "CVE-%s",
-        ),
-        "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
-    }
-
 # Options for c_annotations extension
 # -----------------------------------
 

Doc/constraints.txt

@@ -13,14 +13,12 @@ packaging<25
 Pygments<3
 requests<3
 snowballstemmer<3
-# keep lower-bounds until Sphinx 8.1 is released
-# https://github.com/sphinx-doc/sphinx/pull/12756
-sphinxcontrib-applehelp>=1.0.7,<3
-sphinxcontrib-devhelp>=1.0.6,<3
-sphinxcontrib-htmlhelp>=2.0.6,<3
-sphinxcontrib-jsmath>=1.0.1,<2
-sphinxcontrib-qthelp>=1.0.6,<3
-sphinxcontrib-serializinghtml>=1.1.9,<3
+sphinxcontrib-applehelp<3
+sphinxcontrib-devhelp<3
+sphinxcontrib-htmlhelp<3
+sphinxcontrib-jsmath,<2
+sphinxcontrib-qthelp<3
+sphinxcontrib-serializinghtml<3
 
 # Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
 MarkupSafe<3

Doc/requirements-oldest-sphinx.txt

@@ -7,25 +7,25 @@ blurb
 python-docs-theme>=2022.1
 
 # Generated from:
-#     pip install "Sphinx~=7.2.6"
+#     pip install "Sphinx~=8.1.3"
 #     pip freeze
 #
-# Sphinx 7.2.6 comes from ``needs_sphinx = '7.2.6'`` in ``Doc/conf.py``.
+# Sphinx 8.1.3 comes from ``needs_sphinx = '8.1.3'`` in ``Doc/conf.py``.
 
-alabaster==0.7.16
+alabaster==1.0.0
 babel==2.16.0
 certifi==2024.12.14
-charset-normalizer==3.4.0
-docutils==0.20.1
+charset-normalizer==3.4.1
+docutils==0.21.2
 idna==3.10
 imagesize==1.4.1
 Jinja2==3.1.5
 MarkupSafe==3.0.2
 packaging==24.2
-Pygments==2.18.0
+Pygments==2.19.1
 requests==2.32.3
 snowballstemmer==2.2.0
-Sphinx==7.2.6
+Sphinx==8.1.3
 sphinxcontrib-applehelp==2.0.0
 sphinxcontrib-devhelp==2.0.0
 sphinxcontrib-htmlhelp==2.1.0

Misc/NEWS.d/next/Documentation/2025-01-16-18-59-11.gh-issue-125722.eHHRga.rst

@@ -0,0 +1,2 @@
+Require Sphinx 8.1.3 or later to build the Python documentation. Patch by
+Adam Turner.