From abf6bedc38aea51ecce988a499a0b277bbd3c267 Mon Sep 17 00:00:00 2001 From: John Snow <jsnow@redhat.com> Date: Mon, 10 Mar 2025 23:42:02 -0400 Subject: docs/sphinx: add compat.py module and nested_parse helper Create a compat module that handles sphinx cross-version compatibility issues. For the inaugural function, add a nested_parse_with_titles() helper that handles differences in line number tracking for nested directive body parsing. Spoilers: there are more cross-version hacks to come throughout the series. Signed-off-by: John Snow <jsnow@redhat.com> Message-ID: <20250311034303.75779-5-jsnow@redhat.com> Acked-by: Markus Armbruster <armbru@redhat.com> Signed-off-by: Markus Armbruster <armbru@redhat.com> --- docs/sphinx/compat.py | 35 +++++++++++++++++++++++++++++++++++ 1 file changed, 35 insertions(+) create mode 100644 docs/sphinx/compat.py (limited to 'docs/sphinx/compat.py') diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py new file mode 100644 index 0000000..39b859a --- /dev/null +++ b/docs/sphinx/compat.py @@ -0,0 +1,35 @@ +""" +Sphinx cross-version compatibility goop +""" + +from docutils.nodes import Element + +from sphinx.util import nodes +from sphinx.util.docutils import SphinxDirective, switch_source_input + + +def nested_parse_with_titles( + directive: SphinxDirective, content_node: Element +) -> None: + """ + This helper preserves error parsing context across sphinx versions. + """ + + # necessary so that the child nodes get the right source/line set + content_node.document = directive.state.document + + try: + # Modern sphinx (6.2.0+) supports proper offsetting for + # nested parse error context management + nodes.nested_parse_with_titles( + directive.state, + directive.content, + content_node, + content_offset=directive.content_offset, + ) + except TypeError: + # No content_offset argument. Fall back to SSI method. + with switch_source_input(directive.state, directive.content): + nodes.nested_parse_with_titles( + directive.state, directive.content, content_node + ) -- cgit v1.1