Re: [PATCH 04/57] docs/sphinx: add compat.py module and nested_parse helper

[Markus Armbruster <armbru@redhat.com>]

John Snow <jsnow@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 <jsnow@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 :)