[3.12] gh-117928: Bump the minimum Sphinx version to 6.2.1 (GH-117853) (#118321)

Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com>

.github/workflows/reusable-docs.yml

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

Doc/conf.py

@@ -283,8 +283,8 @@ smartquotes_excludes = {
     'languages': ['ja', 'fr', 'zh_TW', 'zh_CN'], 'builders': ['man', 'text'],
 }
 
-# Avoid a warning with Sphinx >= 2.0
+# Avoid a warning with Sphinx >= 4.0
-master_doc = 'contents'
+root_doc = 'contents'
 
 # Allow translation of index directives
 gettext_additional_targets = [

Doc/requirements-oldest-sphinx.txt

@@ -7,29 +7,29 @@ blurb
 python-docs-theme>=2022.1
 
 # Generated from:
-#     pip install "Sphinx~=4.2.0"
+#     pip install "Sphinx~=6.2.1"
 #     pip freeze
 #
-# Sphinx 4.2 comes from ``needs_sphinx = '4.2'`` in ``Doc/conf.py``.
+# Sphinx 6.2.1 comes from ``needs_sphinx = '6.2.1'`` in ``Doc/conf.py``.
 
-alabaster==0.7.13
+alabaster==0.7.16
-Babel==2.13.0
+Babel==2.14.0
-certifi==2023.7.22
+certifi==2024.2.2
-charset-normalizer==3.3.0
+charset-normalizer==3.3.2
-docutils==0.17.1
+docutils==0.19
-idna==3.4
+idna==3.7
 imagesize==1.4.1
-Jinja2==3.1.2
+Jinja2==3.1.3
-MarkupSafe==2.1.3
+MarkupSafe==2.1.5
-packaging==23.2
+packaging==24.0
-Pygments==2.16.1
+Pygments==2.17.2
 requests==2.31.0
 snowballstemmer==2.2.0
-Sphinx==4.2.0
+Sphinx==6.2.1
-sphinxcontrib-applehelp==1.0.4
+sphinxcontrib-applehelp==1.0.8
-sphinxcontrib-devhelp==1.0.2
+sphinxcontrib-devhelp==1.0.6
-sphinxcontrib-htmlhelp==2.0.1
+sphinxcontrib-htmlhelp==2.0.5
 sphinxcontrib-jsmath==1.0.1
-sphinxcontrib-qthelp==1.0.3
+sphinxcontrib-qthelp==1.0.7
-sphinxcontrib-serializinghtml==1.1.5
+sphinxcontrib-serializinghtml==1.1.10
-urllib3==2.0.7
+urllib3==2.2.1

Doc/tools/extensions/c_annotations.py

@@ -19,7 +19,6 @@
 """
 
 from os import path
-import docutils
 from docutils import nodes
 from docutils.parsers.rst import directives
 from docutils.parsers.rst import Directive
@@ -40,16 +39,6 @@ REST_ROLE_MAP = {
 }
 
 
-# Monkeypatch nodes.Node.findall for forwards compatability
-# This patch can be dropped when the minimum Sphinx version is 4.4.0
-# or the minimum Docutils version is 0.18.1.
-if docutils.__version_info__ < (0, 18, 1):
-    def findall(self, *args, **kwargs):
-        return iter(self.traverse(*args, **kwargs))
-
-    nodes.Node.findall = findall
-
-
 class RCEntry:
     def __init__(self, name):
         self.name = name

Doc/tools/extensions/pyspecific.py

@@ -27,13 +27,7 @@ from sphinx.locale import _ as sphinx_gettext
 from sphinx.util import logging
 from sphinx.util.docutils import SphinxDirective
 from sphinx.writers.text import TextWriter, TextTranslator
-
+from sphinx.util.display import status_iterator
-try:
-    # Sphinx 6+
-    from sphinx.util.display import status_iterator
-except ImportError:
-    # Deprecated in Sphinx 6.1, will be removed in Sphinx 8
-    from sphinx.util import status_iterator
 
 
 ISSUE_URI = 'https://bugs.python.org/issue?@action=redirect&bpo=%s'

Misc/NEWS.d/next/Documentation/2024-04-25-22-12-20.gh-issue-117928.LKdTno.rst

@@ -0,0 +1 @@
+The minimum Sphinx version required for the documentation is now 6.2.1.