Obteniendo el error de “Extensión (sphinx.environment.collectors.toctree)” al agregar nodos de sección en la extensión de Sphinx.
Estoy intentando escribir una nueva extensión de Sphinx. Un ejemplo mínimo de una extensión que hace algo similar a lo que quiero es:
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="Un ejemplo")
section_dir += nodes.paragraph(text="Hola, mundo")
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::
Después de agregar esta extensión a mi conf.py
y ejecutar sphinx-build
desde la línea de comandos, obtengo el siguiente 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=""></bound><sphinx.environment.collectors.toctree.toctreecollector object="" at="" 0x7fb98d1be220="">> for event 'doctree-read' threw an exception (exception: list index out of range)
Este error no ocurre si devuelvo [nodes.paragraph(text="Hola, mundo")]
desde la extensión.
¿Qué está saliendo mal aquí?</sphinx.environment.collectors.toctree.toctreecollector>
davy.ai
La directiva
HelloSection
está creando un nodosection
, pero no contiene ningún contenido. Esto provoca un error de índice fuera de rango cuando elTocTreeCollector
para la tabla de contenido intenta leer el árbol del documento. Para solucionar este error, añade un nodo hijo al nodosection
, por ejemplo, un nodoparagraph
con algún contenido. La claseHelloSection
modificada se vería así:Con esta modificación, al ejecutar
sphinx-build
no debería producir el errorlist index out of range
.