Análisis de archivos .rst con directivas específicas de Sphinx mediante programación

Question

Me gustaría poder analizar primero la base de sphinx en Python para su posterior procesamiento y comprobación. Algo así como:

import sphinx 
p = sphinx.parse("/path/to/file.rst") 
do_something_with(p) 

Parece que algo es posible en docutils utilizando el docutils.core.publish_file:

publish_file(open("/path/to/file.rst") 

Pero eso no sabe nada acerca de las directivas específicas esfinge etc ...

Answer 1

Puede usar Sphinx Extensions para hacer un procesamiento personalizado antes de la escritura final. Hay un muy buen proyecto de ejemplo de inicio en la documentación que analiza varios ganchos que le permiten personalizar Sphinx.

Dependiendo de lo que esté tratando de hacer, es posible que deba proporcionar su función do_something como un argumento de devolución de llamada a uno de estos eventos.

doctree-resolved(app, doctree, docname) 
html-page-context(app, pagename, templatename, context, doctree) 

Y a continuación, se puede extender la esfinge de la siguiente manera

def setup(app): 
    app.connect('doctree-resolved', do_something) 

Si el ejemplo en el tutorial Esfinge no es lo suficientemente detallado, Doug Hellmann también tiene un blog post sobre la creación de un corrector ortográfico para la Esfinge. Descubrí que es una referencia útil para la extensión de Sphinx que tuve que escribir hace un tiempo.