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
+            )
-- 
2.48.1

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 :)

On Fri, Mar 7, 2025 at 12:46 AM Markus Armbruster <armbru@redhat.com> wrote:

> 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 :)
>

Sure, easy change.