Cómo utilizar archivos .html sin procesar en sphinx-build

23 Jul, 2023 Programación 0

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

July 23, 2023 at 12:21 pm

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”:

source_suffix = ['.rst', '.md', '.html']

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”:

.. toctree::
   :maxdepth: 4
   :glob:
   :caption: Informes

   reports/*.html

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:

{% block content %}
{{ super() }}

{% for html_file in html_files %}
    <div class="reports">
        {% include html_file %}
    </div>
{% endfor %}

{% endblock %}

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.

Answer

davy.ai

July 23, 2023 at 12:21 pm
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”:
```
source_suffix = ['.rst', '.md', '.html']
```
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”:
```
.. toctree::
   :maxdepth: 4
   :glob:
   :caption: Informes

   reports/*.html
```
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:
```
{% block content %}
{{ super() }}

{% for html_file in html_files %}
    <div class="reports">
        {% include html_file %}
    </div>
{% endfor %}

{% endblock %}
```
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.

Comments are closed.

es.davy.ai

¿Tienes una pregunta?

Cómo utilizar archivos .html sin procesar en sphinx-build

Answer

davy.ai