¿Cómo preprocesar los archivos de origen mientras se ejecuta un Sphinx?

He configurado una documentación de Sphinx para mi proyecto y me gustaría extraer cadenas de documentos para los archivos de origen e incrustarlos en la documentación final. Desafortunadamente, el idioma del archivo fuente (VHDL) no es compatible con Sphinx. Parece que no hay un dominio Sphinx para VHDL.

Así que mis ideas son las siguientes:

  • Conéctate a la ejecución de Sphinx y ejecuta algún código de Python antes de Sphinx
  • Los códigos de Python extraen bloques de texto de cada archivo de origen (el bloque de comentarios multilínea más alto) y ensamblan un archivo reST por archivo de origen, que consiste en este bloque de comentarios y otro marcado de reST.
  • Todos los archivos de origen se enumeran en un index.rst , para generar la directiva apropiada .. toctree:: .
  • La extracción y transformación de texto se realiza de forma recursiva por directorio de código fuente.

Entonces la pregunta principal es: ¿Cómo enganchar en Spinx?

¿O debería simplemente importar y ejecutar mi propia configuración en conf.py ?

 #!/usr/bin/env python3 # -*- coding: utf-8 -*- # from my_preprocessor import my_proc proc = my_proc() proc.run() # # Test documentation build configuration file, created by # sphinx-quickstart on Tue May 24 11:28:20 2016. # .... 

No puedo modificar los archivos del proceso de comstackción: Makefile y make.bat , porque el proceso de comstackción real se ejecuta en ReadTheDocs.org. RTDs solo ejecuta conf.py

Como se señaló en mis comentarios anteriores y en la respuesta de mertyildiran, la forma oficial de conectarse a Sphinx para un idioma sería crear una extensión para implementar un nuevo dominio para VHDL.

Esto ya se ha hecho para muchos otros lenguajes, por ejemplo, Erlang, PHP, CoffeeScript, y API, por ejemplo, HTTP REST, solo para nombrar algunos de sphinx-contrib . Sin embargo, eso llevará mucho tiempo, lo que no tienes … Por lo tanto, te queda la opción de hacer un análisis rápido y luego conectarlo a tu comstackción de Sphinx de alguna manera.

Ya que estás evitando los ganchos oficiales, esta pregunta se convierte en “¿Cómo ejecuto mi propio código dentro de una comstackción de Sphinx?” Para lo cual, le recomendaría que simplemente siga las instrucciones para una extensión local, es decir, colóquela en un directorio separado, agréguela a su ruta, luego impórtela e invoque. Como se señala en los documentos :

El archivo de configuración se ejecuta como código Python en el momento de la comstackción (utilizando execfile (), y con el directorio actual configurado en su directorio que lo contiene), y por lo tanto puede ejecutar código complejo arbitrario. Sphinx luego lee nombres simples del espacio de nombres del archivo como su configuración.

Sin embargo, como resultado final, esto abre las opciones para usar paquetes de terceros como pyVhdl2Sch (con un guiño a la respuesta de mertyildiran) para crear un esquema y luego escribir los archivos rst estáticos a su alrededor para explicar el esquema.

Estás tratando de usar un martillo para romper una tuerca.

Sphinx se creó originalmente para la nueva documentación de Python, y cuenta con excelentes instalaciones para la documentación de proyectos de Python, pero C / C ++ también es compatible, y se planea agregar soporte especial para otros idiomas. http://www.sphinx-doc.org/en/stable/

VHDL no es actualmente un idioma compatible con Sphinx y debido a que VHDL es un lenguaje de descripción de hardware, su prioridad para convertirse en un idioma compatible debe ser baja. Tienes dos opciones y la primera es también mi sugerencia para ti:

1) Utilice una herramienta de generación de documentación específica de VHDL en lugar de Sphinx

VHDocLhttp://www.volkerschatz.com/hardware/vhdocl.html

Una utilidad de documentación VHDL escrita en Perl, basada en Doxygen.

pyVhdl2Schhttp://laurentcabaret.github.io/pyVhdl2Sch/

pyVhdl2Sch es una herramienta de generación de documentación. Toma archivos VHDL (.vhd) como entrada y genera un esquema pdf / svg / ps / png para cada archivo de entrada. Escrito en Python puro, más amigable con la comunidad, más actualizado.

Sigasi Studio XL Dochttp://www.sigasi.com/products/

Edición de gama alta de Sigasi Studio, que es un producto comercial.

2) Contribuya al proyecto Sphinx y agregue el dominio VHDL

Siga la Guía del desarrollador de Sphinx y familiarícese con la estructura del proyecto. Finalmente, agregue vhdl.py a este directorio de proyecto: https://github.com/sphinx-doc/sphinx/tree/master/sphinx/domains

Esta segunda opción no se puede explicar con una respuesta de StackOverflow. Depende de usted si desea agregar más funcionalidad a un proyecto de código abierto como Sphinx.