diff options
| author | John Snow <jsnow@redhat.com> | 2025-03-10 23:42:02 -0400 |
|---|---|---|
| committer | Markus Armbruster <armbru@redhat.com> | 2025-03-11 10:07:02 +0100 |
| commit | abf6bedc38aea51ecce988a499a0b277bbd3c267 (patch) | |
| tree | 985c1c894102dd44f015c671858619625428340e /docs/sphinx/compat.py | |
| parent | ecf92e3618ab6e6cd7ae151f9c12b9e2a6ead198 (diff) | |
| download | qemu-abf6bedc38aea51ecce988a499a0b277bbd3c267.zip qemu-abf6bedc38aea51ecce988a499a0b277bbd3c267.tar.gz qemu-abf6bedc38aea51ecce988a499a0b277bbd3c267.tar.bz2 | |
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>
Diffstat (limited to 'docs/sphinx/compat.py')
| -rw-r--r-- | docs/sphinx/compat.py | 35 |
1 files changed, 35 insertions, 0 deletions
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 + ) |