GH-125722: Increase minimum supported Sphinx to 8.1.3 (#128922)

.github/workflows/reusable-docs.yml

@@ -76,26 +76,6 @@ jobs:
           --fail-if-improved \
           --fail-if-new-news-nit
 
-  # This build doesn't use problem matchers or check annotations
-  build_doc_oldest_supported_sphinx:
-    name: 'Docs (Oldest Sphinx)'
-    runs-on: ubuntu-latest
-    timeout-minutes: 60
-    steps:
-    - uses: actions/checkout@v4
-      with:
-        persist-credentials: false
-    - name: 'Set up Python'
-      uses: actions/setup-python@v5
-      with:
-        python-version: '3.13'  # known to work with Sphinx 7.2.6
-        cache: 'pip'
-        cache-dependency-path: 'Doc/requirements-oldest-sphinx.txt'
-    - name: 'Install build dependencies'
-      run: make -C Doc/ venv REQUIREMENTS="requirements-oldest-sphinx.txt"
-    - name: 'Build HTML documentation'
-      run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
-
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:
     name: 'Doctest'

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,8 @@ today_fmt = '%B %d, %Y'
 highlight_language = 'python3'
 
 # Minimum version of sphinx required
-needs_sphinx = '7.2.6'
+# Keep this version in sync with ``Doc/requirements.txt``.
+needs_sphinx = '8.1.3'
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.
@@ -376,13 +374,7 @@ html_context = {
 
 # 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
-    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)
-    )
 
 # Path to find HTML templates to override theme
 templates_path = ['tools/templates']
@@ -619,16 +611,6 @@ extlinks = {
 }
 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
+sphinxcontrib-applehelp<3
-# https://github.com/sphinx-doc/sphinx/pull/12756
+sphinxcontrib-devhelp<3
-sphinxcontrib-applehelp>=1.0.7,<3
+sphinxcontrib-htmlhelp<3
-sphinxcontrib-devhelp>=1.0.6,<3
+sphinxcontrib-jsmath<2
-sphinxcontrib-htmlhelp>=2.0.6,<3
+sphinxcontrib-qthelp<3
-sphinxcontrib-jsmath>=1.0.1,<2
+sphinxcontrib-serializinghtml<3
-sphinxcontrib-qthelp>=1.0.6,<3
-sphinxcontrib-serializinghtml>=1.1.9,<3
 
 # Direct dependencies of Jinja2 (Jinja is a dependency of Sphinx, see above)
 MarkupSafe<3

Doc/requirements-oldest-sphinx.txt

@@ -1,35 +0,0 @@
-# Requirements to build the Python documentation, for the oldest supported
-# Sphinx version.
-#
-# We pin Sphinx and all of its dependencies to ensure a consistent environment.
-
-blurb
-python-docs-theme>=2022.1
-
-# Generated from:
-#     pip install "Sphinx~=7.2.6"
-#     pip freeze
-#
-# Sphinx 7.2.6 comes from ``needs_sphinx = '7.2.6'`` in ``Doc/conf.py``.
-
-alabaster==0.7.16
-babel==2.16.0
-certifi==2024.12.14
-charset-normalizer==3.4.0
-docutils==0.20.1
-idna==3.10
-imagesize==1.4.1
-Jinja2==3.1.5
-MarkupSafe==3.0.2
-packaging==24.2
-Pygments==2.18.0
-requests==2.32.3
-snowballstemmer==2.2.0
-Sphinx==7.2.6
-sphinxcontrib-applehelp==2.0.0
-sphinxcontrib-devhelp==2.0.0
-sphinxcontrib-htmlhelp==2.1.0
-sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==2.0.0
-sphinxcontrib-serializinghtml==2.0.0
-urllib3==2.3.0

Doc/requirements.txt

@@ -3,9 +3,10 @@
 # Note that when updating this file, you will likely also have to update
 # the Doc/constraints.txt file.
 
-# Sphinx version is pinned so that new versions that introduce new warnings
+# The Sphinx version is pinned so that new versions that introduce new warnings
 # won't suddenly cause build failures. Updating the version is fine as long
 # as no warnings are raised by doing so.
+# Keep this version in sync with ``Doc/conf.py``.
 sphinx~=8.1.0
 
 blurb

Doc/tools/extensions/c_annotations.py

@@ -16,7 +16,6 @@ import dataclasses
 from pathlib import Path
 from typing import TYPE_CHECKING
 
-import sphinx
 from docutils import nodes
 from docutils.statemachine import StringList
 from sphinx import addnodes
@@ -285,16 +284,6 @@ def setup(app: Sphinx) -> ExtensionMetadata:
     app.connect("builder-inited", init_annotations)
     app.connect("doctree-read", add_annotations)
 
-    if sphinx.version_info[:2] < (7, 2):
-        from docutils.parsers.rst import directives
-        from sphinx.domains.c import CObject
-
-        # monkey-patch C object...
-        CObject.option_spec |= {
-            "no-index-entry": directives.flag,
-            "no-contents-entry": directives.flag,
-        }
-
     return {
         "version": "1.0",
         "parallel_read_safe": True,

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.