docutils-develop — For developer discussions of the implementation.

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

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

An idea how to fix Sphinx's "only" directive with a new internal attribute "title_style" for the nodes.section element.


Attachments:

- [0001-New-internal-attribute-nodes.section.title_style.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/4184882201/b9f8/attachment/0001-New-internal-attribute-nodes.section.title_style.patch) (8.4 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:** Tue Aug 26, 2025 10:32 AM 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/13845#issuecomment-3209397215.


---

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.

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

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

Element after a section from nested parsing may be invalid.
    
`parsers.rst.RSTSTate.nested_parse()` with `match_titles=True` (i.e. support for sections) leads to an invalid document tree, if the nested block contains a section but the element following the nested block is not a section.
    
The [structure model](https://docutils.sourceforge.io/docs/ref/doctree.html#structure-model) ony allows a `<section>` as sibling after a `<section>`.

An invalid doctree can be prevented if the following content is appended to the last nested section instead of its parent. The "nested" directive attempts this but fails if it is called from another nested state machine: In a nested state_machine we cannot access/change the `node` attribute ("insertion point") of the calling state_machine (cf. [r10222]).
A  fix using a new attribute to store the parent state machine of nested state machines is attached.


Attachments:

- [0001-New-attribute-to-store-the-parent-state-machine-of-n.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/4184882201/239b/attachment/0001-New-attribute-to-store-the-parent-state-machine-of-n.patch) (6.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:** Tue Aug 26, 2025 10:25 AM 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/13845#issuecomment-3209397215.


---

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.

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

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

- **status**: open-fixed --> pending-remind



---

**[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:** Tue Aug 26, 2025 10:15 AM 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/13845#issuecomment-3209397215.


---

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.

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

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

- Attachments has changed:

Diff:

~~~~

--- old
+++ new
@@ -0,0 +1 @@
+old_nested_parsing.py (7.5 kB; text/x-python)

~~~~




---

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

**Status:** open-fixed
**Created:** Tue Aug 26, 2025 10:13 AM UTC by Günter Milde
**Last Updated:** Tue Aug 26, 2025 10:13 AM 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/13845#issuecomment-3209397215.


---

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.

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

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

- Attachments has changed:

Diff:

~~~~

--- old
+++ new
@@ -1 +0,0 @@
-old_nested_parsing.py (7.7 kB; text/x-python)

~~~~




---

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

**Status:** open-fixed
**Created:** Tue Aug 26, 2025 10:13 AM UTC by Günter Milde
**Last Updated:** Tue Aug 26, 2025 10:13 AM UTC
**Owner:** nobody


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/13845#issuecomment-3209397215.


---

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.

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

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

---

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

**Status:** open-fixed
**Created:** Tue Aug 26, 2025 10:13 AM UTC by Günter Milde
**Last Updated:** Tue Aug 26, 2025 10:13 AM UTC
**Owner:** nobody
**Attachments:**

- [old_nested_parsing.py](https://sourceforge.net/p/docutils/bugs/511/attachment/old_nested_parsing.py) (7.7 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/13845#issuecomment-3209397215.


---

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.

[Docutils-develop] [docutils:bugs] #510 Release date for 0.22 is in the future

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

- **status**: open --> open-fixed
- **Comment**:

Thanks for the report. This is fixed in the repository. A fixup release will take some time, because of [bugs:#508] and [bugs:#509] prove tricky...



---

**[bugs:#510] Release date for 0.22 is in the future**

**Status:** open-fixed
**Created:** Mon Aug 25, 2025 06:21 AM UTC by Dilian Wesselinov Palauzov
**Last Updated:** Mon Aug 25, 2025 06:21 AM UTC
**Owner:** nobody


According to https://docutils.sourceforge.io/HISTORY.html docutils 0.22 was released in 2026, but in fact it was published in 2025.


---

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.

[Docutils-develop] [docutils:bugs] #503 LaTeX writer fails to generate "labels" for some elements with "ids".

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

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r10219].



---

**[bugs:#503] LaTeX writer fails to generate "labels" for some elements with "ids".**

**Status:** open-fixed
**Created:** Wed Jun 04, 2025 04:34 PM UTC by Günter Milde
**Last Updated:** Wed Jun 04, 2025 04:34 PM UTC
**Owner:** nobody


Most doctree elements (nodes) accept the "ids" attribute that can be used as end-point for internal cross references.
In LaTeX, "ids" are represented as "labels". This is only implemented for a small subset of elements.
For example the internal hyperlink in 
~~~
.. note::
   :name: my-note
   
   This is an admonition with ID
   
Link to my-note_. 
~~~
does not work because there is no `\label{my-note}`  in the LaTeX output.

See also [Sphinx issue #13609](https://github.com/sphinx-doc/sphinx/issues/13609#issuecomment-2937289148).


---

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.

[Docutils-develop] [docutils:patches] #214 Give better messages on malformed tables

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

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r10208]. Thank you for report and patch.



---

**[patches:#214] Give better messages on malformed tables**

**Status:** open-fixed
**Group:** None
**Created:** Sun Jun 08, 2025 05:58 PM UTC by Jynn Nelson
**Last Updated:** Thu Jul 31, 2025 01:06 PM UTC
**Owner:** nobody
**Attachments:**

- [tables.diff](https://sourceforge.net/p/docutils/patches/214/attachment/tables.diff) (5.2 kB; application/octet-stream)


This does several things:
- Specifies `Misaligned right border` for that error, instead of just "malformed table".
- Shows the line where each error happened, not the line where the table starts.
  - This had a complication that line numbers appear to be wrong when `include` directives are present (they include the lines in the source document, instead of being relative to the included document). Just disabled the new smarter logic in that case.
- Changes `malformed_table` to require both detail and an offset, so poor errors like this can't happen in the future.

Fixes https://sourceforge.net/p/docutils/bugs/504/.


---

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

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

[Docutils-develop] [docutils:bugs] #504 errors for malformed tables do not indicate what the error is

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

- **status**: open --> open-fixed
- **Comment**:

Fixed in [r10208]. Thank you for report and patch.



---

**[bugs:#504] errors for malformed tables do not indicate what the error is**

**Status:** open-fixed
**Created:** Thu Jun 05, 2025 09:04 PM UTC by Jynn Nelson
**Last Updated:** Sun Jul 20, 2025 10:00 PM UTC
**Owner:** nobody
**Attachments:**

- [table.rst](https://sourceforge.net/p/docutils/bugs/504/attachment/table.rst) (1.1 kB; application/octet-stream)


The error messages for malformed tables are quite long and do not indicate where the error occurred. I expect docutils to point at a single line of code, and say why it was malformed. Instead it points at the whole table and just says "malformed table".

~~~
$ grep PRETTY /etc/os-release
PRETTY_NAME="Pop!_OS 22.04 LTS"
$ python -V
Python 3.10.12
$ docutils -V
docutils (Docutils 0.21.2, Python 3.10.12, on linux)
$ docutils --traceback table.rst >/dev/null
table.rst:5: (ERROR/3) Malformed table.

+-------------------------+-------------------+
| Standard Code           | Message(s)       |
+=========================+===================+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M1, indicator undefined | Illegal reference |
+-------------------------+-------------------+
| M2, Invalid combination | None              |
+-------------------------+-------------------+
~~~

Note that docutils *does*  have the information to report this bug, because I can see it in a debugger. It simply doesn't include that info in the error.

~~~
$ python -m pdb $(which docutils) --traceback table.rst
> /home/jyn/.local/bin/docutils(3)<module>()
-> import re
(Pdb) break docutils/parsers/rst/states.py:1787
Breakpoint 1 at /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py:1787
(Pdb) c
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1787)malformed_table()
-> message = 'Malformed table.'
(Pdb) up
> /home/jyn/.local/lib/python3.10/site-packages/docutils/parsers/rst/states.py(1737)isolate_grid_table()
-> messages.extend(self.malformed_table(block))
(Pdb) list
1732 	            else:
1733 	                messages.extend(self.malformed_table(block))
1734 	                return [], messages, blank_finish
1735 	        for i in range(len(block)):     # check right edge
1736 	            if len(block[i]) != width or block[i][-1] not in '+|':
1737 ->	                messages.extend(self.malformed_table(block))
1738 	                return [], messages, blank_finish
1739 	        return block, messages, blank_finish
1740 	
1741 	    def isolate_simple_table(self):
1742 	        start = self.state_machine.line_offset
(Pdb) p block[i]
'| Standard Code           | Message(s)       |'
(Pdb) p width
47
(Pdb) p len(block[i])
46
~~~


---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

Good news. 
The remaining warnings are from a different issue (see the comment by Peter Maydell).
I will do some more testing and cleanups. Then we can  release a new Docutils version.
Thank you for report and testing.


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Sun Aug 17, 2025 07:17 PM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

Could you re-try with a checkout or snapshot of [r10204] that introduces independent section title style hierarchies for nested parsing?


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Fri Aug 15, 2025 09:24 AM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] Re: #508 qemu build problem after docutils update to 0.22

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

Looking at `docs/sphinx/kerneldoc.py`, I see that it uses Docutil's `RSTState.nested_parse()` which (up to now) forces a consistent title style hierarchy. 
OTOH, *quapidoc* uses Sphinx's `nested_parse_with_titles()` that starts a new title style hierarchy.
Could you check, if the remaining CRITICAL errors also show up with Docutils 0.21?


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Thu Aug 14, 2025 07:44 PM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

I am working on a fix...


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Thu Aug 14, 2025 09:26 AM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

- **Comment**:

Did you check the generated HTML for missing section headings?
While the build runs without crashing, there are still serious errors.

Unfortunately, I cannot replicate or trace the reason.
Here is what I found so far:

The error is in docstrings that are collected by a Sphinx  extension (qapidoc?).

The error message tells, that the parser expects a consistent hierarchy of title adornment styles (i.e. sections in docstrings under/overlined with `*`, subsections underlined with `-`).  Docstrings using this style (e.g. /scratch/emulators/qemu/work/qemu-10.0.3/qapi/pci.json) don't report an error any more.

The mystery is, that Sphinx "autodoc" and (as far as I can see in the [source](https://gitlab.com/qemu-project/qemu/-/blob/master/docs/sphinx/qapidoc.py?ref_type=heads#L469)) "qapidoc"  set up a "fresh" title style hierarchy for docstrings (with the auxiliary functions `nested_parse_with_titles()` rsp. `nested_parse_to_nodes()`).
Nevertheless, the docstrings in `include/hw/qdev-core.h` and `system/qtest.c` are parsed with a non-empty section title style hierarchy.

The traceback of a run with a "docutils.conf" file in the project directory that sets
halt_level to 3 may give some hints.

As a workaround, you may consider "normalizing" the section title adornments in `include/hw/qdev-core.h` and `system/qtest.c`.



---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Mon Aug 11, 2025 09:20 PM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

Yes, Docutils now checks, whether the new "self.parent" after switching the section level is valid and reports these CRITICAL system messages (downgraded to ERROR in [r10198].

However, there is still a serious problem: an incompatibility with "qapidoc" rsp `sphinx.util.nodes.nested_parse_with_titles()`.
This should be fixed in [r10200]. 
Can you re-try?


For added robustness, I recommend that "qapidoc" switches from using `sphinx.util.nodes.nested_parse_with_titles()` to `sphinx.util.parsing.nested_parse_to_nodes()` as recommended in the docstring
of nested_parse_with_titles();

> This function is retained for compatibility and will be deprecated in
    Sphinx 8. Prefer ``nested_parse_to_nodes()``.
    
  Then, "qapidoc" should also work with Docutils 0.22.



---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Fri Aug 08, 2025 08:56 PM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #509 regression with docutils 0.22: unsupported operand type(s) for +: 'NoneType' and 'list'

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

In this case, the problem seems to be an incompatibility with Sphinx's "autoprogram".
Can you please try with an updated repository version of Docutils?
Commit [r10200] should fix it.



---

**[bugs:#509] regression with docutils 0.22: unsupported operand type(s) for +: 'NoneType' and 'list'**

**Status:** open
**Created:** Wed Aug 06, 2025 06:13 PM UTC by Oliver Smith
**Last Updated:** Thu Aug 07, 2025 07:18 PM UTC
**Owner:** nobody


Hello,

after upgrading to docutils 0.22, building documentation for the pmbootstrap project fails:

~~~
    Traceback (most recent call last):
      File "/usr/lib/python3.12/site-packages/sphinx/cmd/build.py", line 432, in build_main
        app.build(args.force_all, args.filenames)
      File "/usr/lib/python3.12/site-packages/sphinx/application.py", line 426, in build
        self.builder.build_update()
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 375, in build_update
        self.build(
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 403, in build
        updated_docnames = set(self.read())
                               ^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 519, in read
        self._read_serial(docnames)
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 584, in _read_serial
        self.read_doc(docname)
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
      File "/usr/lib/python3.12/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/sphinx/io.py", line 103, in read
        self.parse()
      File "/usr/lib/python3.12/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
      File "/usr/lib/python3.12/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
               ^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
                 ^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/sphinxcontrib/autoprogram.py", line 262, in run
        nested_parse_with_titles(self.state, result, node)
      File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2787, in underline
        self.section(title, source, style, lineno - 1, messages)
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/lib/python3.12/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
~~~

Source code:
https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/

Tested with commit:
5927ff70b8d2468d5d0e2c978bc1fe30d036fd7f

Distribution:
Alpine Linux Edge


---

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.

[Docutils-develop] [docutils:patches] #200 Add the gemini:// URI scheme

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

- **status**: open --> pending-remind
- **Comment**:

Thank you for the contribution.
Unfortunately, we cannot include the patch without a change in the Docutils specification,
https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks,
which limits the supported URI schemes to the ones listed in the Official IANA Registry of URI Schemes and the W3C's Retired Index of WWW Addressing Schemes.

While I don't see a "gemini" URI scheme as a particular problematic case, adding non-registered schemes should be done with special care and consideration. Up to now, we (as Docutils developers) did not start to take this task onto ourselfs but relied on the abovementined sources.

Mind, that the mapping in `doctuils.utils.urischemes` only considers the recognition of [standalone hyperlinks](https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#standalone-hyperlinks). At places where an URI is expected (the link block of external hyperlink targets or the argument of an "image" or "figure" directive) any scheme is recognised, so the creation of valid "gemini" links is possible as, e.g.,
~~~
A link_, `anonymous link`__, 
`indirect link with embedded target <link_>`__, 
`link with embedded URI <gemini://example.org/gemtext3>`__.

The reference text of links with embedded target may also be omitted, in which case the URI will be duplicated for use as the reference text:
so `<gemini://example.org/gemtext3>`__ gives the same result as a standalone hyperlink.

gemini://example.org/other-gemtext
.. _link: gemini://example.org/my-gemtext
__ gemini://example.org/other-gemtext
~~~



---

**[patches:#200] Add the gemini:// URI scheme**

**Status:** pending-remind
**Group:** None
**Created:** Tue Dec 20, 2022 04:40 PM UTC by Fabien LOISON
**Last Updated:** Tue Dec 20, 2022 04:40 PM UTC
**Owner:** nobody
**Attachments:**

- [gemini.patch](https://sourceforge.net/p/docutils/patches/200/attachment/gemini.patch) (529 Bytes; text/x-patch)


Hello,

I am currently working on a tool to convert reStructuredText files to Gemtext and I noticed the `gemini://...` URIs (used by the [Gemini Protocol](https://en.wikipedia.org/wiki/Gemini_(protocol))) were not automatically converted into links. 

I attached a small patch that adds the `gemini` scheme to the `docutils.utils.urischemes.schemes` dictionary.


---

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

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

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

Could you re-try with [r10197] or the attached patch if this gets a more telling log or and maybe some output?


Attachments:

- [0001-Catch-invalid-node.parent-when-switching-section-lev.patch](https://sourceforge.net/p/docutils/bugs/_discuss/thread/e488751d7e/e5ae/attachment/0001-Catch-invalid-node.parent-when-switching-section-lev.patch) (3.4 kB; text/x-patch)


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Fri Aug 08, 2025 05:12 PM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

What is strange, though is that Sphinx' autodoc extension does not have a problem with the new section parsing algorithm. Which extension does the extraction of docstrings rsp. the combination of the docstrings into a document?


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Fri Aug 08, 2025 10:05 AM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

You are right. As also seen in [#509], the CRITICAL errors are just on top of the problem (and helped to find the reasong beeing some "docstring reading" extension (plus docstrings that include section headings) beeing incompatible with Docutils 0.22.
(Unfortunately, the new section algorithm was only tested with Sphinx, not with Sphinx extensions and docstrings containing section headings.)


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Thu Aug 07, 2025 01:36 PM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:bugs] #509 regression with docutils 0.22: unsupported operand type(s) for +: 'NoneType' and 'list'

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

This looks like the problem reported in [bugs:508].

Could you check the Sphinx log?
Do you use "autodoc" or similar extensions to extract docstrings?


---

**[bugs:#509] regression with docutils 0.22: unsupported operand type(s) for +: 'NoneType' and 'list'**

**Status:** open
**Created:** Wed Aug 06, 2025 06:13 PM UTC by Oliver Smith
**Last Updated:** Wed Aug 06, 2025 06:13 PM UTC
**Owner:** nobody


Hello,

after upgrading to docutils 0.22, building documentation for the pmbootstrap project fails:

~~~
    Traceback (most recent call last):
      File "/usr/lib/python3.12/site-packages/sphinx/cmd/build.py", line 432, in build_main
        app.build(args.force_all, args.filenames)
      File "/usr/lib/python3.12/site-packages/sphinx/application.py", line 426, in build
        self.builder.build_update()
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 375, in build_update
        self.build(
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 403, in build
        updated_docnames = set(self.read())
                               ^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 519, in read
        self._read_serial(docnames)
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 584, in _read_serial
        self.read_doc(docname)
      File "/usr/lib/python3.12/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
      File "/usr/lib/python3.12/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/sphinx/io.py", line 103, in read
        self.parse()
      File "/usr/lib/python3.12/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
      File "/usr/lib/python3.12/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2354, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
               ^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
                 ^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/sphinxcontrib/autoprogram.py", line 262, in run
        nested_parse_with_titles(self.state, result, node)
      File "/usr/lib/python3.12/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
                  ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
               ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 2787, in underline
        self.section(title, source, style, lineno - 1, messages)
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
      File "/usr/lib/python3.12/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/lib/python3.12/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
~~~

Source code:
https://gitlab.postmarketos.org/postmarketOS/pmbootstrap/

Tested with commit:
5927ff70b8d2468d5d0e2c978bc1fe30d036fd7f

Distribution:
Alpine Linux Edge


---

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.

[Docutils-develop] [docutils:bugs] #508 qemu build problem after docutils update to 0.22

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

The reason is an incompatibility of Sphinx or one of the Sphinx extensions with the new section parsing algorithm introduced in commit [r10093] with updates in  [r10129], [r10131], [r10131].

The unhelpful "TypeError" is displayed because Sphinx carries on after a CRITICAL problem which leads to follow-up problems (here, `self.parent` beeing None instead of an Element instance).

The error reported by Docutils gives some hints. Let's dissect the first message:
~~~
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
~~~
It provides the source file and line (system/qtest.c, line 70) and a reason (`Inconsistent title style: skip from level 1 to 3.`).

How does it come to this conclusion:

* The parser keeps a record of section adornment styles in the `memo`
  attribute of the `document` object. These are the "Established title
  styles" (under- and overline with `=` for level 1, underline
  with `-` for level 2, and underline with `^` for level 3. 
  The new section header uses an underline with `^`.  
  Hence, the new section should be at level 3.

* The current section level is determined scanning the parent elements
  of the current element for `<section>` elements.
  Level 1 means that one parent section was found.
 
A the level (depth) of a section element is determined from its physical nesting level, it is impossible to represent a level 3 section inside a level 1 section in the doctree.

### Why does the Docutils update trigger this problem?

The source is a docstring in a C file. Some extension must have been used to extract it and include it (together with other docstrings) in a wrapper document. 

When including a source, there are two strategies to handle section adornment styles:
1.  enforce a consistent style hierarchy across all included parts,
2.  establish a new style hierarchy for the included parts.

It seems as if with previous Docutisl versions there was strategy 2 and now its stratagy 1.
This is most likely not intended but a side effect of the changes to the inner working of the parser.
To fix it, we would need to know which extension is used to extract the docstrings and cooperate with its developers.


---

**[bugs:#508] qemu build problem after docutils update to 0.22**

**Status:** open
**Created:** Mon Aug 04, 2025 08:23 AM UTC by Thomas Klausner
**Last Updated:** Mon Aug 04, 2025 08:23 AM UTC
**Owner:** nobody


After updating docutils in pkgsrc to 0.22 (with sphinx 8.2.3), qemu 10.0.3 (https://gitlab.com/qemu-project/qemu) stopped building. The output is not very clear:
```
[5596/6204] Generating docs/QEMU manual with a custom command
FAILED: [code=2] docs/docs.stamp
/scratch/emulators/qemu/work/.tools/bin/env CONFDIR=/usr/pkg/etc/qemu/qemu /scratch/emulators/qemu/work/qemu-10.0.3/build/pyvenv/bin/sphinx-build -q -j auto -Dversion=10.0.3 -Drelease= -Ddepfile=docs/docs.d -Ddepfile_sta
mp=docs/docs.stamp -b html -d /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual.p /scratch/emulators/qemu/work/qemu-10.0.3/docs /scratch/emulators/qemu/work/qemu-10.0.3/build/docs/manual
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
Possible precedence problem between ! and pattern match (m//) at /scratch/emulators/qemu/work/qemu-10.0.3/docs/../scripts/kernel-doc line 1597.
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:70: CRITICAL: Inconsistent title style: skip from level 1 to 3.

Valid requests
^^^^^^^^^^^^^^

Established title styles: =/= - ^ [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:73: CRITICAL: Inconsistent title style: skip from level 1 to 4.
                                                                                                                                                                                                          10:17:35 [41/1829]
Clock management:
"""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:107: CRITICAL: Inconsistent title style: skip from level 1 to 4.

PIO and memory access:
""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:215: CRITICAL: Inconsistent title style: skip from level 1 to 4.

IRQ management:
"""""""""""""""

Established title styles: =/= - ^ " [docutils]
/scratch/emulators/qemu/work/qemu-10.0.3/docs/../system/qtest.c:239: CRITICAL: Inconsistent title style: skip from level 1 to 4.

Setting interrupt level:
""""""""""""""""""""""""

Established title styles: =/= - ^ " [docutils]

Sphinx parallel build error!

Versions
========

* Platform:         netbsd11; (NetBSD-11.99.1-amd64-x86_64-64bit-ELF)
* Python version:   3.13.5 (CPython)
* Sphinx version:   8.2.3
* Docutils version: 0.22
* Jinja2 version:   3.1.6
* Pygments version: 2.19.2

Last Messages
=============


    reading sources... [ 91%]
    system/s390x/protvirt .. system/target-loongarch

    reading sources... [ 94%]
    system/target-m68k .. system/target-sparc64

    reading sources... [ 97%]
    system/target-xtensa .. tools/qemu-nbd

Loaded Extensions
=================

* sphinx.ext.mathjax (8.2.3)
* alabaster (1.0.0)
* sphinxcontrib.applehelp (2.0.0)
* sphinxcontrib.devhelp (2.0.0)
* sphinxcontrib.htmlhelp (2.1.0)
* sphinxcontrib.serializinghtml (2.0.0)
* sphinxcontrib.qthelp (2.0.0)
* depfile (1.0)
* hxtool (1.0)
* kerneldoc (1.0)
* qapi_domain (1.0)
* qapidoc (2.0)
* qmp_lexer (unknown version)
* dbusdoc (1.0)
* sphinxcontrib.jquery (4.1)
* sphinx_rtd_theme (unknown version)

Traceback
=========

      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 137, in _join_one
        raise SphinxParallelError(*result)
    sphinx.errors.SphinxParallelError: TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'


The full traceback has been saved in:
/tmp/sphinx-err-gj6pt4nj.log

To report this error to the developers, please open an issue at <https://github.com/sphinx-doc/sphinx/issues/>. Thanks!
Please also report this if it was a user error, so that a better error message can be provided next time.
```

The full traceback from the log lists docutils code as the origin of the breakage:
```
Traceback
=========

    (Error in parallel process)
    Traceback (most recent call last):
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/parallel.py", line 83, in _process
        ret = func(arg)  # type: ignore[call-arg]
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 603, in read_process
        self.read_doc(docname, _cache=False)
        ~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/builders/__init__.py", line 648, in read_doc
        publisher.publish()
        ~~~~~~~~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/core.py", line 269, in publish
        self.document = self.reader.read(self.source, self.parser,
                        ~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^
                                         self.settings)
                                         ^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/io.py", line 103, in read
        self.parse()
        ~~~~~~~~~~^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/readers/__init__.py", line 101, in parse
        self.parser.parse(self.input, document)
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/parsers.py", line 86, in parse
        self.statemachine.run(inputlines, document, inliner=self.inliner)
        ~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 165, in run
        results = StateMachineWS.run(self, input_lines, input_offset,
                                     input_source=document['source'])
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2356, in explicit_markup
        self.explicit_list(blank_finish)
        ~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2381, in explicit_list
        newline_offset, blank_finish = self.nested_list_parse(
                                       ~~~~~~~~~~~~~~~~~~~~~~^
              self.state_machine.input_lines[offset:],
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
        ...<2 lines>...
              blank_finish=blank_finish,
              ^^^^^^^^^^^^^^^^^^^^^^^^^^
              match_titles=self.state_machine.match_titles)
              ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 312, in nested_list_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2659, in explicit_markup
        nodelist, blank_finish = self.explicit_construct(match)
                                 ~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2366, in explicit_construct
        return method(self, expmatch)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2103, in directive
        return self.run_directive(
               ~~~~~~~~~~~~~~~~~~^
            directive_class, match, type_name, option_presets)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 2153, in run_directive
        result = directive_instance.run()
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 620, in run
        contentnode = self.transmogrify(schema)
      File "/scratch/emulators/qemu/work/qemu-10.0.3/docs/sphinx/qapidoc.py", line 549, in transmogrify
        nested_parse_with_titles(self.state, content, contentnode)
        ~~~~~~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/sphinx/util/nodes.py", line 378, in nested_parse_with_titles
        ret = state.nested_parse(content, content_offset, node, match_titles=True)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 275, in nested_parse
        state_machine.run(block, input_offset, memo=self.memo,
        ~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
                          node=node, match_titles=match_titles)
                          ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 191, in run
        results = StateMachineWS.run(self, input_lines, input_offset)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 235, in run
        context, next_state, result = self.check_line(
                                      ~~~~~~~~~~~~~~~^
            context, state, transitions)
            ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/statemachine.py", line 447, in check_line
        return method(match, context, next_state)
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 3024, in text
        self.section(title.lstrip(), source, style, lineno + 1, messages)
        ~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 321, in section
        self.new_subsection(title, lineno, messages)
        ~~~~~~~~~~~~~~~~~~~^^^^^^^^^^^^^^^^^^^^^^^^^
      File "/usr/pkg/lib/python3.13/site-packages/docutils/parsers/rst/states.py", line 370, in new_subsection
        self.parent += section_node
      File "/usr/pkg/lib/python3.13/site-packages/docutils/nodes.py", line 736, in __radd__
        return other + self.children
               ~~~~~~^~~~~~~~~~~~~~~
    TypeError: unsupported operand type(s) for +: 'NoneType' and 'list'
```
Even with the  "CRITICAL: Inconsistent title style" problems fixed, the build stops.
Any ideas what the problem is or how to fix it?
Thanks.



---

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.

[Docutils-develop] [docutils:feature-requests] #66 allow more characters when transforming "names" to "ids".

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

See also the discussion in [Sphinx issue #8709](https://github.com/sphinx-doc/sphinx/issues/8709).


---

**[feature-requests:#66] allow more characters when transforming "names" to "ids".**

**Status:** pending
**Group:** Default
**Created:** Mon Sep 30, 2019 05:30 PM UTC by Roland Puntaier
**Last Updated:** Tue Apr 29, 2025 07:07 PM UTC
**Owner:** nobody


    `` encloses a role. There is a default role, else :<role>:`text`

    _ in front, is the special target role. For one word the backtick can be dropped.

    _`__init__` should produce a target named "__init__".

But instead the produced target is "init".
The backtick avoids ambiguity. There is no need for this behavior.



---

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

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

[Docutils-develop] [docutils:bugs] #502 Duplicate target not always recognized.

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

- **status**: open-fixed --> closed-fixed
- **Comment**:

Fixed in Docutils 0.22. 
Commit [r10176]  makes targets from hyperlink references with embedded URI or alias implicit.



---

**[bugs:#502] Duplicate target not always recognized.**

**Status:** closed-fixed
**Created:** Tue Jun 03, 2025 09:33 AM UTC by Günter Milde
**Last Updated:** Thu Jul 31, 2025 01:20 PM UTC
**Owner:** nobody


Hyperlinks with embedded alias generate both, a `<reference>` and a `<target>`. 
This allows simple references to the target:
~~~
See `here <example.html>`_.

As we have shown here_, ...
~~~
However, it may lead to duplicates:
~~~
_`Here` is an explicit inline target.

See `here <example.html>`_.

As we have shown here_, ...
~~~
The second target gives a WARNING `Duplicate explicit target name: "here".`
Using the reference name results in an ERROR `Duplicate target name, cannot be used as a unique reference: "here".`

However (in versions up to 0.22.rc2), the duplicate target is ignored in case of **embedded internal** targets:
~~~
_`Here` is an explicit inline target.

See `here <elsewhere_>`_.

As we have shown here_, ...

The target is _`elsewhere`.
~~~
There is no WARNING or ERROR and both references link to "elsewhere".

This is fixed in [r10151].


---

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.