在狮身人面像扩展中添加部分节点时获得"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是字符串列表，而不是字符串