python - 在 Sphinx 扩展中添加节节点时获取 "Extension error (sphinx.environment.collectors.toctree)"

Question

我正在尝试编写一个新的 Sphinx 扩展。一个与我想要的类似的扩展的最小示例是

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::

将此扩展添加到我的 conf.py 并从命令行运行 sphinx-build 后，我收到以下错误

$ 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)

如果我从扩展中返回 [nodes.paragraph(text="Hello, world")]，则不会发生此错误。

这里出了什么问题？

Answer 1

我遇到了同样的问题。我调试了内部 Sphinx 代码，发现 ids 属性对于 toctree 内的部分是必需的:

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

注意!

• 该 ID 在整个页面中必须是唯一的。
• ids 是一个字符串列表，而不是一个字符串