On Fri, Mar 7, 2025 at 12:46 AM Markus Armbruster <arm...@redhat.com> wrote:
> 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 :) > Sure, easy change.
