How to avoid doctree-read exception when writing new directive extension

[Thomas A. Christensen II]

Hi all,

I'm trying to write my first Sphinx extension. It is a directive that adds a new section based on parsing a config file. As long as I return paragraph nodes, then the directive works fine, but when I return section nodes, the program errors out with the following message:

$ sphinx-build docs _build
Running Sphinx v4.2.0
building [mo]: targets for 0 po files that are out of date
building [html]: targets for 2 source files that are out of date
updating environment: [new config] 2 added, 0 changed, 0 removed
reading sources... [100%] test
Extension error (sphinx.environment.collectors.toctree):
Handler <bound method TocTreeCollector.process_doc of <sphinx.environment.collectors.toctree.TocTreeCollector object at 0x7f5803601190>> for event
      'doctree-read' threw an exception (exception: list index out of range)

This is what a stripped down version of my extension looks like:

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,
    }

And my conf.py

import os
import sys
sys.path.append(os.path.abspath('./_ext'))

project = 'extension-testing'
copyright = '2022, Thomas Christensen'
author = 'Thomas Christensen'

extensions = [
    'hellosection',
]

html_theme = 'alabaster'

I'm having trouble even debugging this to find out where the error actually is. Can anyone please tell me what I'm doing wrong and how to fix it?

Thank you,
Thomas Christensen

[Komiya Takeshi]

Hi,

Sphinx expects all section nodes have their node_id. So please call
`document.note_implicit_target(section_node)` inside your directive.

Thanks,
Takeshi KOMIYA

2022年1月7日(金) 3:00 Thomas A. Christensen II <tchris...@vet.k-state.edu>:

> --
> You received this message because you are subscribed to the Google Groups "sphinx-users" group.
> To unsubscribe from this group and stop receiving emails from it, send an email to sphinx-users...@googlegroups.com.
> To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/572fc7c8-9d92-1739-9e40-6e4414f993be%40vet.k-state.edu.

[Embodiment_Geniuslm3]

AKfycbxmMDiSj2CLoAkM0NSFvTknj796x8pqMzUgG7E4Ow1tvIYtLjAx7hAjDr3-fV45fsDLbQ

To view this discussion on the web visit https://groups.google.com/d/msgid/sphinx-users/CAFmkQANfS55W%3DD5MwKgGfR6GnCvy2T0R7a2zuXHG_RZhRgtp8A%40mail.gmail.com.