[RFC,v2,10/35] docs/qapi-domain: add compatibility node classes

Commit Message

John Snow Dec. 13, 2024, 1:12 a.m. UTC

Sphinx prior to v4.0 uses different classes for rendering elements of
documentation objects; add some compatibility classes to use the right
node classes conditionally.
Signed-off-by: John Snow <[e-mail]>
---
 docs/sphinx/compat.py | 17 ++++++++++++++++-
 1 file changed, 16 insertions(+), 1 deletion(-)

Patch

diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py
index 4c8d1e94530..28cb39161fe 100644
--- a/docs/sphinx/compat.py
+++ b/docs/sphinx/compat.py
@@ -2,12 +2,27 @@ 
 Sphinx cross-version compatibility goop
 """
 
-from docutils.nodes import Element
+from typing import Callable
 
+from docutils.nodes import Element, Node, Text
+
+import sphinx
+from sphinx import addnodes
 from sphinx.util.docutils import SphinxDirective, switch_source_input
 from sphinx.util.nodes import nested_parse_with_titles
 
 
+space_node: Callable[[str], Node]
+keyword_node: Callable[[str, str], Node]
+
+if sphinx.version_info[:3] >= (4, 0, 0):
+    space_node = addnodes.desc_sig_space
+    keyword_node = addnodes.desc_sig_keyword
+else:
+    space_node = Text
+    keyword_node = addnodes.desc_annotation
+
+
 def nested_parse(directive: SphinxDirective, content_node: Element) -> None:
     """
     This helper preserves error parsing context across sphinx versions.