[3.12] Doc: Upgrade Sphinx to 8.1 (GH-125276) (#125279)

Doc: Upgrade Sphinx to 8.1 (GH-125276)
(cherry picked from commit dd0ee20)

Co-authored-by: Adam Turner <[email protected]>

Author: miss-islington

Doc/conf.py

@@ -11,6 +11,8 @@
 import sys
 import time
 
+import sphinx
+
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
 
@@ -56,7 +58,10 @@
 
 # General substitutions.
 project = 'Python'
-copyright = f"2001-{time.strftime('%Y')}, Python Software Foundation"
+if sphinx.version_info[:2] >= (8, 1):
+    copyright = "2001-%Y, Python Software Foundation"
+else:
+    copyright = f"2001-{time.strftime('%Y')}, Python Software Foundation"
 
 # We look for the Include/patchlevel.h file in the current Python source tree
 # and replace the values accordingly.
@@ -339,10 +344,14 @@
 }
 
 # This 'Last updated on:' timestamp is inserted at the bottom of every page.
-html_time = int(os.environ.get('SOURCE_DATE_EPOCH', time.time()))
-html_last_updated_fmt = time.strftime(
-    '%b %d, %Y (%H:%M UTC)', time.gmtime(html_time)
-)
+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)
+    )
 
 # Path to find HTML templates.
 templates_path = ['tools/templates']
@@ -575,13 +584,21 @@
 # mapping unique short aliases to a base URL and a prefix.
 # https://www.sphinx-doc.org/en/master/usage/extensions/extlinks.html
 extlinks = {
-    "cve": ("https://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s", "CVE-%s"),
-    "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
     "pypi": ("https://pypi.org/project/%s/", "%s"),
     "source": (SOURCE_URI, "%s"),
 }
 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://cve.mitre.org/cgi-bin/cvename.cgi?name=CVE-%s",
+            "CVE-%s",
+        ),
+        "cwe": ("https://cwe.mitre.org/data/definitions/%s.html", "CWE-%s"),
+    }
+
 # Options for c_annotations
 # -------------------------
 

Doc/requirements.txt

@@ -6,7 +6,7 @@
 # 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.
-sphinx~=8.0.0
+sphinx~=8.1.0
 
 blurb