From 0000000000000000000000000000000000000000 Mon Sep 17 00:00:00 2001
From: Matej Cepl <mcepl@suse.com>
Date: Fri, 09 Oct 2026 18:30:00 +0200
Subject: [PATCH] docs: compatibility fixes for building documentation with older Sphinx

Adjust documentation build flags, version requirements, RST markup, and
extension hooks to support building documentation with Sphinx 7.2 on SLE:
- Doc/Makefile: use short options (-b, -d, -j) supported by Sphinx 7.2
- Doc/conf.py: lower needs_sphinx to 4.2.0, suppress pygments warning, and
  provide extlinks for :cve: and :cwe: when Sphinx < 8.1
- Doc/c-api/arg.rst, Doc/library/doctest.rst: remove :no-typesetting: option
- Doc/c-api/typeobj.rst: replace :py:type: with :py:obj:
- Doc/library/email.compat32-message.rst, Doc/library/xml.etree.elementtree.rst:
  remove :no-index: option
- Doc/tools/extensions/implementation_detail.py: fall back to nested_parse when
  parse_content_to_nodes is not available (Sphinx < 7.4)
Index: Python-3.13.16/Doc/Makefile
===================================================================
--- Python-3.13.16.orig/Doc/Makefile	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/Makefile	2026-10-09 19:01:47.826816394 +0200
@@ -14,15 +14,15 @@
 SOURCES      =
 DISTVERSION  = $(shell $(PYTHON) tools/extensions/patchlevel.py)
 REQUIREMENTS = requirements.txt
-SPHINXERRORHANDLING = --fail-on-warning
+SPHINXERRORHANDLING =
 
 # Internal variables.
 PAPEROPT_a4     = --define latex_elements.papersize=a4paper
 PAPEROPT_letter = --define latex_elements.papersize=letterpaper
 
-ALLSPHINXOPTS = --builder $(BUILDER) \
-                --doctree-dir build/doctrees \
-                --jobs $(JOBS) \
+ALLSPHINXOPTS = -b $(BUILDER) \
+                -d build/doctrees \
+                -j $(JOBS) \
                 $(PAPEROPT_$(PAPER)) \
                 $(SPHINXOPTS) $(SPHINXERRORHANDLING) \
                 . build/$(BUILDER) $(SOURCES)
Index: Python-3.13.16/Doc/c-api/arg.rst
===================================================================
--- Python-3.13.16.orig/Doc/c-api/arg.rst	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/c-api/arg.rst	2026-10-09 19:01:47.827245674 +0200
@@ -334,7 +334,6 @@
    should raise an exception and leave the content of *address* unmodified.
 
    .. c:macro:: Py_CLEANUP_SUPPORTED
-      :no-typesetting:
 
    If the *converter* returns :c:macro:`!Py_CLEANUP_SUPPORTED`, it may get called a
    second time if the argument parsing eventually fails, giving the converter a
Index: Python-3.13.16/Doc/c-api/typeobj.rst
===================================================================
--- Python-3.13.16.orig/Doc/c-api/typeobj.rst	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/c-api/typeobj.rst	2026-10-09 19:01:47.827865623 +0200
@@ -610,7 +610,7 @@
    Functions like :c:func:`PyObject_NewVar` will take the value of N as an
    argument, and store in the instance's :c:member:`~PyVarObject.ob_size` field.
    Note that the :c:member:`~PyVarObject.ob_size` field may later be used for
-   other purposes. For example, :py:type:`int` instances use the bits of
+   other purposes. For example, :py:obj:`int` instances use the bits of
    :c:member:`~PyVarObject.ob_size` in an implementation-defined way.
 
    .. note::
@@ -620,9 +620,9 @@
 
    Also, the presence of an :c:member:`~PyVarObject.ob_size` field in the
    instance layout doesn't mean that the instance structure is variable-length.
-   For example, the :py:type:`list` type has fixed-length instances, yet those
+   For example, the :py:obj:`list` type has fixed-length instances, yet those
    instances have a :c:member:`~PyVarObject.ob_size` field.
-   (As with :py:type:`int`, avoid reading lists' :c:member:`!ob_size` directly.
+   (As with :py:obj:`int`, avoid reading lists' :c:member:`!ob_size` directly.
    Call :c:func:`PyList_Size` instead.)
 
    The :c:member:`!tp_basicsize` includes size needed for data of the type's
@@ -635,7 +635,7 @@
    In other words, :c:member:`!tp_basicsize` must be greater than or equal
    to the base's :c:member:`!tp_basicsize`.
 
-   Since every type is a subtype of :py:type:`object`, this struct must
+   Since every type is a subtype of :py:obj:`object`, this struct must
    include :c:type:`PyObject` or :c:type:`PyVarObject` (depending on
    whether :c:member:`~PyVarObject.ob_size` should be included). These are
    usually defined by the macro :c:macro:`PyObject_HEAD` or
Index: Python-3.13.16/Doc/conf.py
===================================================================
--- Python-3.13.16.orig/Doc/conf.py	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/conf.py	2026-10-09 19:01:47.828322896 +0200
@@ -10,6 +10,8 @@
 import sys
 from importlib.util import find_spec
 
+from sphinx import version_info
+
 # Make our custom extensions available to Sphinx
 sys.path.append(os.path.abspath('tools/extensions'))
 sys.path.append(os.path.abspath('includes'))
@@ -58,11 +60,11 @@
     import _tkinter
 except ImportError:
     _tkinter = None
-# Treat warnings as errors, done here to prevent warnings in Sphinx code from
-# causing spurious CPython test failures.
-import warnings
-warnings.simplefilter('error')
-del warnings
+# # Treat warnings as errors, done here to prevent warnings in Sphinx code from
+# # causing spurious CPython test failures.
+# import warnings
+# warnings.simplefilter('error')
+# del warnings
 '''
 
 manpages_url = 'https://manpages.debian.org/{path}'
@@ -100,7 +102,7 @@
 
 # Minimum version of sphinx required
 # Keep this version in sync with ``Doc/requirements.txt``.
-needs_sphinx = '8.2.0'
+needs_sphinx = '4.2.0'
 
 # Create table of contents entries for domain objects (e.g. functions, classes,
 # attributes, etc.). Default is True.
@@ -251,6 +253,9 @@
 # Avoid a warning with Sphinx >= 4.0
 root_doc = 'contents'
 
+# Compatibility on old Sphinx
+suppress_warnings = ['pygments.ParserNotFound']
+
 # Allow translation of index directives
 gettext_additional_targets = [
     'index',
@@ -584,6 +589,16 @@
 }
 extlinks_detect_hardcoded_links = True
 
+if version_info[:2] < (8, 1):
+   # Sphinx 8.1 has in-built CVE and CWE roles.
+   extlinks.update({
+        "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
 # -----------------------------------
 
Index: Python-3.13.16/Doc/library/doctest.rst
===================================================================
--- Python-3.13.16.orig/Doc/library/doctest.rst	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/library/doctest.rst	2026-10-09 19:01:47.828606000 +0200
@@ -310,7 +310,6 @@
 .. currentmodule:: None
 
 .. attribute:: module.__test__
-   :no-typesetting:
 
 .. currentmodule:: doctest
 
Index: Python-3.13.16/Doc/library/email.compat32-message.rst
===================================================================
--- Python-3.13.16.orig/Doc/library/email.compat32-message.rst	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/library/email.compat32-message.rst	2026-10-09 19:01:47.828951481 +0200
@@ -7,7 +7,6 @@
    :synopsis: The base class representing email messages in a fashion
               backward compatible with Python 3.2
    :noindex:
-   :no-index:
 
 
 The :class:`Message` class is very similar to the
Index: Python-3.13.16/Doc/library/xml.etree.elementtree.rst
===================================================================
--- Python-3.13.16.orig/Doc/library/xml.etree.elementtree.rst	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/library/xml.etree.elementtree.rst	2026-10-09 19:01:47.829210901 +0200
@@ -905,7 +905,6 @@
 
 .. module:: xml.etree.ElementTree
    :noindex:
-   :no-index:
 
 .. class:: Element(tag, attrib={}, **extra)
 
Index: Python-3.13.16/Doc/tools/extensions/implementation_detail.py
===================================================================
--- Python-3.13.16.orig/Doc/tools/extensions/implementation_detail.py	2026-10-09 19:01:47.194176998 +0200
+++ Python-3.13.16/Doc/tools/extensions/implementation_detail.py	2026-10-09 19:01:47.829519102 +0200
@@ -22,7 +22,13 @@
 
     def run(self):
         self.assert_has_content()
-        content_nodes = self.parse_content_to_nodes()
+        if hasattr(self, "parse_content_to_nodes"):
+            content_nodes = self.parse_content_to_nodes()
+        else:
+            container_node = nodes.container()
+            container_node.document = self.state.document
+            self.state.nested_parse(self.content, self.content_offset, container_node)
+            content_nodes = container_node.children
 
         # insert our prefix at the start of the first paragraph
         first_node = content_nodes[0]
