Cómo utilizar archivos .html sin procesar en sphinx-build
Digamos que tengo esta estructura en mi carpeta de origen para la documentación de Sphinx:
journals /
archivos *.md
reports /
archivos *.html
conf.py
index.rst
y el siguiente código en index.rst:
.. toctree::
:maxdepth: 4
:glob:
:caption: Informes
reports/*
.. toctree::
:maxdepth: 4
:glob:
:caption: Revistas
journals/*
Cuando genero mis documentos con sphinx-build, Sphinx construye automáticamente las páginas HTML resultantes con los archivos .md encontrados en mi carpeta “journals”, pero ignora los archivos .html encontrados en la carpeta “reports”.
Lo que quisiera es que Sphinx incluya automáticamente los archivos .html encontrados en la carpeta “reports”. Las páginas .html resultantes deben incluir aún el diseño de Sphinx (barra lateral, encabezados, etc.) y no ser una simple copia de los archivos .html sin formato.
Sé que podría hacer archivos .rst con lo siguiente:
.. raw:: html
:file: reports/archivo.html
Básicamente, esto hace lo que quiero. Sphinx encuentra el archivo .rst y crea un archivo .html que incluye tanto el diseño de Sphinx como mi archivo fuente .html.
Sin embargo, no sé cómo hacer esto automáticamente, ya que tengo muchos archivos en mi carpeta “reports”. Preferiría evitar tener que crear un archivo .rst para cada uno de mis archivos .html.
¿Hay alguna forma de automatizar este proceso con sphinx-build?
davy.ai
Sí, hay una forma de automatizar el proceso de incluir archivos .html en su documentación Sphinx con sphinx-build.
En primer lugar, es necesario modificar el archivo “conf.py” para indicar a Sphinx que trate los archivos “.html” como fuentes. Para hacer eso, agregue la siguiente línea al archivo “conf.py”:
Esto indica a Sphinx que los archivos .html también deben tratarse como fuentes.
En segundo lugar, es necesario modificar el archivo “index.rst” agregando una nueva directiva “toctree” que incluya los archivos “.html” de la carpeta “reports”. Para hacer eso, agregue las siguientes líneas al archivo “index.rst”:
Esto le indica a Sphinx que incluya todos los archivos .html de la carpeta “reports” en la tabla de contenidos con el título especificado.
Por último, es necesario modificar la plantilla que Sphinx utiliza para generar las páginas HTML para incluir los archivos “.html” de la carpeta “reports”.
Para hacer eso, es necesario crear un nuevo archivo de plantilla llamado “layout.html” (o usar uno existente si ya ha creado una plantilla personalizada) en la carpeta “_templates”. Luego, agregue las siguientes líneas al archivo de plantilla:
Este bloque de código indica a Sphinx que incluya todos los archivos .html de la carpeta “reports” al iterar sobre ellos e incluirlos en el elemento “div” con el atributo “class” establecido en “reports”.
Después de hacer estos cambios, reconstruya la documentación utilizando “sphinx-build” y las páginas HTML resultantes deberían incluir tanto los archivos “.md” de la carpeta “journals” como los archivos “.html” de la carpeta “reports”, con el diseño de Sphinx aplicado a ambos.