SF.net SVN: docutils:[10206] trunk/docutils
milde--- via Docutils-checkins <[email protected]> Tue, 19 Aug 2025 16:53:34 +0000
| Newsgroups | gmane.text.docutils.cvs |
|---|---|
| Message-ID | <[email protected]> |
Revision: 10206
http://sourceforge.net/p/docutils/code/10206
Author: milde
Date: 2025-08-19 16:53:27 +0000 (Tue, 19 Aug 2025)
Log Message:
-----------
rST parser: ensure that nested parsing only appends to the provided base node.
* Always start a new title style hierarchy for nested parsing.
* Append sections to the base node also if it is not a `<document>`
or `<section>` (revert [r10203]).
This change makes the behaviour of nested parsing more uniform and predictable
(independent of type and possible parents of the base node).
It prevents problems with silently dropped higher level sections
in Docutils < 0.22 (because the legacy "raise error and retry" algorithm
of section parsing fails with nested parsing).
It also prevents a wrong node order for sections in Docutils 0.22
(because the calling parser has no means to know the new "insertion point"
and continues where it left before the nested parsing).
Modified Paths:
--------------
trunk/docutils/HISTORY.rst
trunk/docutils/RELEASE-NOTES.rst
trunk/docutils/docs/ref/rst/directives.rst
trunk/docutils/docs/ref/rst/restructuredtext.rst
trunk/docutils/docutils/parsers/rst/states.py
trunk/docutils/test/test_parsers/test_rst/test_nested_parsing.py
Modified: trunk/docutils/HISTORY.rst
===================================================================
--- trunk/docutils/HISTORY.rst 2025-08-19 15:07:47 UTC (rev 10205)
+++ trunk/docutils/HISTORY.rst 2025-08-19 16:53:27 UTC (rev 10206)
@@ -24,17 +24,18 @@
* docutils/nodes.py
- `nodes.Element.section_hierarchy()` now returns only elements
- with non-empty `.parent`.
+ with non-empty "parent" attribute.
* docutils/parsers/rst/states.py
- - Relax "section title" system message from SEVERE to ERROR.
+ - Relax "section title" system messages from SEVERE to ERROR.
- Ensure new "current node" is valid when switching section level
(cf. bugs #508 and #509).
- - `NestedStateMachine.run()` uses a separate title style hierarchy
- if the base node is not attached to the document (cf. bug #508).
+ - Use a `separate title style hierarchy for nested parsing`__.
+__ RELEASE-NOTES.html#nested-parsing
+
Release 0.22 (2026-07-29)
=========================
Modified: trunk/docutils/RELEASE-NOTES.rst
===================================================================
--- trunk/docutils/RELEASE-NOTES.rst 2025-08-19 15:07:47 UTC (rev 10205)
+++ trunk/docutils/RELEASE-NOTES.rst 2025-08-19 16:53:27 UTC (rev 10206)
@@ -261,12 +261,30 @@
============================
reStructuredText parser:
- Nested parsing uses a separate title style hierarchy
- if the base node is not attached to the document.
+ _`Nested parsing` uses a separate section `title style hierarchy`_ if
+ `states.RSTState.nested_parsing()` is used with ``match_titles=True``.
+ Content included via nested parsing may use section title styles in
+ different order, all sections become sub-sections (or sub-sub-section...)
+ of the current section level. [#]_
+ This ensures that all elements generated by the nested parsing are
+ added to the provided base node (without possible data loss as in
+ Docutils < 0.22).
+ No changes are required to document sources that work fine
+ in Docutils <= 0.22.
+
+ .. [#] similar to Sphinx's `sphinx.util.node.nested_parse_with_titles()`
+ and overriding the ``keep_title_context`` argument of
+ `sphinx.util.parsing.nested_parse_to_nodes()`__
+
+ __ https://www.sphinx-doc.org/en/master/extdev/utils.html
+ #sphinx.util.parsing.nested_parse_to_nodes
+
Bugfixes and improvements (see HISTORY_).
+.. _title style hierarchy: docs/ref/rst/restructuredtext.html#title-styles
+
Release 0.22 (2025-07-29)
=========================
Modified: trunk/docutils/docs/ref/rst/directives.rst
===================================================================
--- trunk/docutils/docs/ref/rst/directives.rst 2025-08-19 15:07:47 UTC (rev 10205)
+++ trunk/docutils/docs/ref/rst/directives.rst 2025-08-19 16:53:27 UTC (rev 10206)
@@ -1646,8 +1646,8 @@
Parse the included content with the specified parser.
See the `"parser" configuration setting`_ for available parsers.
- Starts a new "`section hierarchy`_" (all sections in the included
- content become subsections of the current section).
+ Starts a new `section title style hierarchy`_ (all sections in the
+ included content become subsections of the current section).
.. Caution::
There is is no check whether the inserted elements are valid at the
@@ -2315,7 +2315,7 @@
.. _hyperlink target: restructuredtext.html#hyperlink-targets
.. _reference name:
.. _reference names: restructuredtext.html#reference-names
-.. _section hierarchy: restructuredtext.html#sections
+.. _section title style hierarchy: restructuredtext.html#title-styles
.. _simple table: restructuredtext.html#simple-tables
.. _supported length units: restructuredtext.html#length-units
Modified: trunk/docutils/docs/ref/rst/restructuredtext.rst
===================================================================
--- trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-08-19 15:07:47 UTC (rev 10205)
+++ trunk/docutils/docs/ref/rst/restructuredtext.rst 2025-08-19 16:53:27 UTC (rev 10206)
@@ -596,6 +596,8 @@
next title of the same or higher level are included in a section (or
subsection, etc.).
+.. _title styles:
+
All section title styles need not be used, nor need any specific
section title style be used. However, a document must be consistent
in its use of section titles: once a hierarchy of title styles is
Modified: trunk/docutils/docutils/parsers/rst/states.py
===================================================================
--- trunk/docutils/docutils/parsers/rst/states.py 2025-08-19 15:07:47 UTC (rev 10205)
+++ trunk/docutils/docutils/parsers/rst/states.py 2025-08-19 16:53:27 UTC (rev 10206)
@@ -186,8 +186,7 @@
"""
Parse `input_lines` and populate `node`.
- Use a separate "title style hierarchy" if `node` is not
- attached to the document (changed in Docutils 0.23).
+ Use a separate "title style hierarchy" (changed in Docutils 0.23).
Extend `StateMachineWS.run()`: set up document-wide data.
"""
@@ -199,13 +198,11 @@
self.reporter = self.document.reporter
self.node = node
if match_titles:
- # Start a new title style hierarchy if `node` is not
- # a descendant of the `document`:
- _root = node
- while _root.parent is not None:
- _root = _root.parent
- if _root != self.document:
- self.memo.title_styles = []
+ # Use a separate section title style hierarchy;
+ # ensure all sections in the `input_lines` are treated as
+ # subsections of the current section by blocking lower
+ # section levels with a style that is impossible in rST:
+ self.memo.title_styles = ['x'] * len(node.section_hierarchy())
results = StateMachineWS.run(self, input_lines, input_offset)
assert results == [], ('NestedStateMachine.run() results should be '
'empty!')
@@ -282,16 +279,13 @@
:input_offset:
Line number at start of the block.
:node:
- Base node. Generated nodes will be appended to this node
- (unless a new section with lower level is encountered, see below).
+ Base node. All generated nodes will be appended to this node.
:match_titles:
Allow section titles?
- If the base `node` is attached to the document, new sections will
- be appended according their level in the section hierarchy
- (moving up the tree).
- If the base `node` is *not* attached to the document,
- a separate section title style hierarchy is used for the nested
+ A separate section title style hierarchy is used for the nested
parsing (all sections are subsections of the current section).
+ The calling code should check whether sections are valid
+ children of the base node and move them or warn otherwise.
:state_machine_class:
Default: `NestedStateMachine`.
:state_machine_kwargs:
@@ -406,12 +400,7 @@
if newlevel > len(title_styles):
title_styles.append(style)
self.memo.section_level = newlevel
- if newlevel > oldlevel:
- # new section is a subsection: get the current section or base node
- while self.parent.parent and not isinstance(
- self.parent, (nodes.section, nodes.document)):
- self.parent = self.parent.parent
- else:
+ if newlevel <= oldlevel:
# new section is sibling or higher up in the section hierarchy
self.parent = parent_sections[newlevel-1].parent
return True
Modified: trunk/docutils/test/test_parsers/test_rst/test_nested_parsing.py
===================================================================
--- trunk/docutils/test/test_parsers/test_rst/test_nested_parsing.py 2025-08-19 15:07:47 UTC (rev 10205)
+++ trunk/docutils/test/test_parsers/test_rst/test_nested_parsing.py 2025-08-19 16:53:27 UTC (rev 10206)
@@ -1,6 +1,6 @@
#! /usr/bin/env python3
-# $Id$
-# Author: David Goodger <[email protected]>
+# $id$
+# author: David Goodger <[email protected]>
# Copyright: This module has been placed in the public domain.
"""
@@ -180,15 +180,13 @@
current1
********
- sec1.2
+ current1.1
-----------
- Sibling section appended 1 level up.
-
- sec2
- =========
+ current1.1.1
+ ============
Top-level section appended to document.
-Succeeding paragraph. TODO: currently misplaced!
+Succeeding paragraph.
""",
"""\
<document source="test data">
@@ -201,18 +199,16 @@
<section ids="current1" names="current1">
<title>
current1
+ <section ids="current1-1" names="current1.1">
+ <title>
+ current1.1
+ <section ids="current1-1-1" names="current1.1.1">
+ <title>
+ current1.1.1
+ <paragraph>
+ Top-level section appended to document.
<paragraph>
- Succeeding paragraph. TODO: currently misplaced!
- <section ids="sec1-2" names="sec1.2">
- <title>
- sec1.2
- <paragraph>
- Sibling section appended 1 level up.
- <section ids="sec2" names="sec2">
- <title>
- sec2
- <paragraph>
- Top-level section appended to document.
+ Succeeding paragraph.
"""],
# parse into attached wrapper node:
["""\
@@ -224,11 +220,10 @@
attached1
*********
- sec2
- =========
- Nested top-level section appended to document.
+ attached1.1
+ ===========
-Succeeding paragraph. TODO: currently misplaced!
+Succeeding paragraph.
""",
"""\
<document source="test data">
@@ -239,16 +234,14 @@
<title>
sec1.1
<sidebar>
- <section ids="attached1" names="attached1">
- <title>
- attached1
+ <section ids="attached1" names="attached1">
+ <title>
+ attached1
+ <section ids="attached1-1" names="attached1.1">
+ <title>
+ attached1.1
<paragraph>
- Succeeding paragraph. TODO: currently misplaced!
- <section ids="sec2" names="sec2">
- <title>
- sec2
- <paragraph>
- Nested top-level section appended to document.
+ Succeeding paragraph.
"""],
# detached base node -> start new section hierarchy
["""\
This was sent by the SourceForge.net collaborative development platform, the world's largest Open Source development site.