John Snow <js...@redhat.com> writes: > Create a compat module that handles sphinx cross-version compatibility > issues. For the inaugural function, add a nested_parse() 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 <js...@redhat.com> > --- > docs/sphinx/compat.py | 33 +++++++++++++++++++++++++++++++++ > 1 file changed, 33 insertions(+) > create mode 100644 docs/sphinx/compat.py > > diff --git a/docs/sphinx/compat.py b/docs/sphinx/compat.py > new file mode 100644 > index 00000000000..792aca10e39 > --- /dev/null > +++ b/docs/sphinx/compat.py > @@ -0,0 +1,33 @@ > +""" > +Sphinx cross-version compatibility goop > +""" > + > +from docutils.nodes import Element > + > +from sphinx.util.docutils import SphinxDirective, switch_source_input > +from sphinx.util.nodes import nested_parse_with_titles > + > + > +def nested_parse(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 > + 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): > + nested_parse_with_titles( > + directive.state, directive.content, content_node > + )
The function wraps around sphinx.util.nodes.nested_parse_with_titles(). Would calling it nested_parse_with_titles() reduce readers' cognitive load at call sites? Please do not misinterpret my question as a demand. It's really just a question :)
