[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.