[Docutils-develop] [docutils:bugs] #511 Problems with nested parsing and sections.

[Günter M. <mi...@us...>]

Commit [r10226] fixes the [regeression in Sphinx](https://github.com/sphinx-doc/sphinx/issues/13861).
In order to correctly support sections in nested parsing, it reverts to using `memo.section_level` to keep record of the current section level.
This is cumbersome and error prone because it needs to be updated with every switch
of the current node.

The attached patch implements an alternative:
Store the difference between the intended start level of nested parsing and the
number of parents of the base node in the new attribute `section_level_offset`.
Use it to correct the section level determined via `node.section_hierarchy()`.


Attachments:

- [0001-rST-parser-Use-section_level_offset-instead-of-memo..patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/4184882201/424c/attachment/0001-rST-parser-Use-section_level_offset-instead-of-memo..patch) (7.0 kB; text/x-patch)


---

**[bugs:#511] Problems with nested parsing and sections.**

**Status:** pending-remind
**Created:** Tue Aug 26, 2025 10:13 AM UTC by Günter Milde
**Last Updated:** Mon Sep 08, 2025 07:09 PM UTC
**Owner:** nobody
**Attachments:**

- [old_nested_parsing.py](https://sourceforge.net/p/docutils/bugs/511/attachment/old_nested_parsing.py) (7.5 kB; text/x-python)


In Docutils <= 0.22, parsing a nested content block with `docutils.parsers.rst.state.RSTState.nested_parse()` uses the document-wide "title style hierarchy".

With Docutils <=0.21, this method can **loose complete sections** without warning when the `match_titles` argument is True and the nested content block contains sections with a title style that matches a lower section level than the current section level (try the attached test with a Docutils version below 0.22).

Docutils itself does not use `nested_parse()` with `match_titles` True and did not test.
However, the feature is used by Sphinx and several Sphinx extensions (cf. [bugs:#508], [bugs:#509], and  https://github.com/sphinx-doc/sphinx/issues/13845).

The new section parsing algorithm introduced in Docutils 0.22 fixes the data loss, but  sections with a title style that matches a lower section level than the current section level are attached in wrong order: After the nested parsing is complete, the calling parser continues where it left of, messing the order of elements in the doctree (try the attached test with [r10204]).

This was fixed in [r10206] at the expense of dropping support for document-wide title styles in nested parsing. 
As a result, the Sphinx "only" directive (which uses a new section style hierarchy with later re-attachment of the first section) now fails: https://github.com/sphinx-doc/sphinx/issues/13861


---

Sent from sourceforge.net because doc...@li... is subscribed to https://sourceforge.net/p/docutils/bugs/

To unsubscribe from further messages, a project admin can change settings at https://sourceforge.net/p/docutils/admin/bugs/options.  Or, if this is a mailing list, you can unsubscribe from the mailing list.