From 7fa3b85c60a015d326400590caa827c365e470f6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnter=20Milde?= Date: Tue, 9 Sep 2025 16:17:15 +0200 Subject: [PATCH 1/2] Fix test setup for directive tests. Set the "parent" attribute of RSTState instances to the `document` instead of None. The attribute holds the state machines "current node" which is initialized to the `document` in `RSTStateMachine.run()` and required since Docutils 0.22.1 in `RSTState.nested_parse()` to correctly support sections in nested parsing. --- tests/test_util/test_util_docutils_sphinx_directive.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tests/test_util/test_util_docutils_sphinx_directive.py b/tests/test_util/test_util_docutils_sphinx_directive.py index eb1e4aea16a..0f4e558d885 100644 --- a/tests/test_util/test_util_docutils_sphinx_directive.py +++ b/tests/test_util/test_util_docutils_sphinx_directive.py @@ -38,7 +38,7 @@ def make_directive_and_state( inliner = Inliner() inliner.init_customizations(document.settings) state.inliner = inliner - state.parent = None + state.parent = document state.memo = SimpleNamespace( document=document, reporter=document.reporter, From 5f00fab21d8eae045013180928a85a6e2807fd03 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?G=C3=BCnter=20Milde?= Date: Mon, 11 Aug 2025 17:16:16 +0200 Subject: [PATCH 2/2] Fix docstring of sphinx.util.parsing.nested_parse_to_nodes(). "section" elements can only be children of "document" or "section" elements, not "sidebar". Cf. https://docutils.sourceforge.io/docs/ref/doctree.html#section --- sphinx/util/parsing.py | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/sphinx/util/parsing.py b/sphinx/util/parsing.py index 4c4a6477683..61c2e07fcf2 100644 --- a/sphinx/util/parsing.py +++ b/sphinx/util/parsing.py @@ -39,8 +39,7 @@ def nested_parse_to_nodes( Note that this option bypasses Docutils' usual checks on doctree structure, and misuse of this option can lead to an incoherent doctree. In Docutils, section nodes should - only be children of ``Structural`` nodes, which includes - ``document``, ``section``, and ``sidebar`` nodes. + only be children of ``document`` or ``section`` nodes. :param keep_title_context: If this is False (the default), then *content* is parsed as if it were an independent document, meaning that title decorations (e.g. underlines) @@ -49,6 +48,9 @@ def nested_parse_to_nodes( a completely different context, such as docstrings. If this is True, then title underlines must match those in the surrounding document, otherwise the behaviour is undefined. + Warning: Up to Docutils 0.21, sections with an decoration style + matching a level that is higher than the current section level are + silently discarded! Since Docutils 0.22.1, an error is reported. .. versionadded:: 7.4 """