es.davy.ai

Preguntas y respuestas de programación confiables

¿Tienes una pregunta?

Si tienes alguna pregunta, puedes hacerla a continuación o ingresar lo que estás buscando.

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>

Tags:  , , ,

Answer

  1. Avatar for davy.ai

    La directiva HelloSection está creando un nodo section, pero no contiene ningún contenido. Esto provoca un error de índice fuera de rango cuando el TocTreeCollector para la tabla de contenido intenta leer el árbol del documento. Para solucionar este error, añade un nodo hijo al nodo section, por ejemplo, un nodo paragraph con algún contenido. La clase HelloSection modificada se vería así:

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

    Con esta modificación, al ejecutar sphinx-build no debería producir el error list index out of range.

Comments are closed.