From 01b94f5702a2d40f0fe14971b3ffbd7dd0723f63 Mon Sep 17 00:00:00 2001
From: John Parent <john.parent@kitware.com>
Date: Mon, 15 Jun 2026 10:30:56 -0400
Subject: [PATCH] Help: Restore sphinx pre-5.0 compatibility

Revise commit 97d13c3053 (Help: Improve diagnostics documentation,
2026-04-30, v4.4.0-rc1~227^2~2) to switch `cmake.py`'s sphinx api usage
from 7.4+ features to 4.0+ features.

Replace `parse_text_to_nodes` and `parse_content_to_nodes` with
equivalent, backwards compatible sphinx code using existing api calls.

Signed-off-by: John Parent <john.parent@kitware.com>
---
 Utilities/Sphinx/cmake.py | 20 ++++++++++++++------
 1 file changed, 14 insertions(+), 6 deletions(-)

diff --git a/Utilities/Sphinx/cmake.py b/Utilities/Sphinx/cmake.py
index 391e98f8f4..2743c14def 100644
--- a/Utilities/Sphinx/cmake.py
+++ b/Utilities/Sphinx/cmake.py
@@ -13,6 +13,7 @@ import sphinx
 # The following imports may fail if we don't have Sphinx 2.x or later.
 if sphinx.version_info >= (2,):
     from docutils import io, nodes
+    from docutils.statemachine import ViewList
     from docutils.nodes import Element, Node, TextElement, system_message
     from docutils.parsers.rst import Directive, directives
     from docutils.transforms import Transform
@@ -145,6 +146,12 @@ logger = logging.getLogger(__name__)
 sig_end_re = re.compile(r'(?<=[)])\n')
 
 
+def _parse_rst(state, text: str) -> list[Node]:
+    node = nodes.Element()
+    state.nested_parse(ViewList([text], source=''), 0, node)
+    return node.children
+
+
 @dataclass
 class ObjectEntry:
     docname: str
@@ -559,7 +566,7 @@ class CMakeDiagnosticObject(CMakeObject):
 
     def _build_field(self, name: str, content: str | list[Node]) -> Node:
         if type(content) is not list:
-            content = self.parse_text_to_nodes(content)
+            content = _parse_rst(self.state,content)
 
         name_node = nodes.field_name(text=name)
         body_node = nodes.field_body('', *content)
@@ -568,13 +575,13 @@ class CMakeDiagnosticObject(CMakeObject):
     def _build_cli(self) -> list[Node]:
         cname = self.targetname[4:].lower().replace('_', '-')
         ctext = f'-W[no-][error=]{cname}'
-        return self.parse_text_to_nodes(f':option:`{ctext} <cmake -W>`')
+        return _parse_rst(self.state,f':option:`{ctext} <cmake -W>`')
 
     def _build_preset_refs(self) -> list[Node]:
         p = self._preset_name()
         w = f':preset:`warnings.{p} <configurePresets.warnings.{p}>`'
         e = f':preset:`errors.{p} <configurePresets.errors.{p}>`'
-        return self.parse_text_to_nodes(f'{w}, {e}')
+        return _parse_rst(self.state,f'{w}, {e}')
 
     def run(self) -> list[Node]:
         self.domain, self.objtype = self.name.split(':', 1)
@@ -590,11 +597,12 @@ class CMakeDiagnosticObject(CMakeObject):
         headers += self._build_field('Default', default)
 
         if parent:
-            parentRef = self.parse_text_to_nodes(f':diagnostic:`{parent}`')
+            parentRef = _parse_rst(self.state,f':diagnostic:`{parent}`')
             headers += self._build_field('Parent', parentRef)
 
-        content = self.parse_content_to_nodes()
-        return [headers] + content
+        node = nodes.Element()
+        self.state.nested_parse(self.content, self.content_offset, node)
+        return [headers] + node.children
 
 
 class CMakeReferenceRole: