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

SourceForge Headquarters 1320 Columbia Street Suite 310 San Diego, CA 92101 +1 (858) 422-6466

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.