Getting "Extension error (sphinx.environment.collectors.toctree)" when adding section nodes in Sphinx extension

Question

I am trying to write a new Sphinx extension. A minimum example of an extension that does something similar to what I want is

from docutils import nodes
from docutils.parsers.rst import Directive

class HelloSection(Directive):
    def run(self):
        section_dir = nodes.section()
        section_dir += nodes.title(text="An example")
        section_dir += nodes.paragraph(text="Hello, world")

        return [section_dir]

def setup(app):
    app.add_directive('hellosection', HelloSection)
    return {
        "version": "0.1.0",
        "parallel_read_safe": False,
        "parallel_write_safe": False,
    }

Test document
=============

.. hellosection::

After adding this extension to my conf.py, and running sphinx-build from the command line, I get the following error

$ sphinx-build -b html docs docs/_build -a -E
Running Sphinx v4.2.0
building [mo]: all of 0 po files
building [html]: all source files
updating environment: [new config] 7 added, 0 changed, 0 removed
reading sources... [ 42%] test-document                                                                                                                                                                   
Extension error (sphinx.environment.collectors.toctree):
Handler <bound method TocTreeCollector.process_doc of <sphinx.environment.collectors.toctree.TocTreeCollector object at 0x7fb98d1be220>> for event 'doctree-read' threw an exception (exception: list index out of range)

This error does not occur if I return [nodes.paragraph(text="Hello, world")] from the extension.

What is going wrong here?

Answer 1

I had the same issue. I debugged the internal Sphinx code and found that ids property is mandatory for sections inside a toctree:

section_dir = nodes.section(ids=["section-unique-id"])

Attention!

• The id must be unique across the page.
• ids is a list os strings, not a string