how - sphinx python example

¿Cómo puedo configurar Sphinx para excluir condicionalmente algunas páginas?

Question

Al generar documentación con Sphinx, me gustaría poder generar dos versiones de mi documentación: una que incluya todo y otra con solo un conjunto de páginas en particular. ¿Cuál es la mejor manera de lograrlo?

Podría escribir un script de compilación que mueva los archivos para lograr esto, pero sería muy bueno si hubiera una manera de decirle a la esfinge que excluya o incluya documentos particulares durante una compilación particular.

Answer 1

¿Qué hay de ifconfig ? Establece los valores de configuración en su archivo conf.py Como es un archivo de Python normal, puede hacer que sus criterios de inclusión sean inteligentes y automáticos si lo necesita.

Answer 2

Tal vez mi respuesta llegue un poco tarde, pero logré hacer esto con Sphinx a través de los patrones de exclusión en el archivo de configuración .

Mi documentación es en parte para los usuarios y en parte para los administradores.
Algunas páginas tienen nombres de archivos que contienen la palabra admin , y como usted, quería crear dos versiones: una con todo (la documentación del administrador) y otra con todas las páginas "admin" excluidas (la documentación del usuario).

Para excluir todas las páginas "admin" en todas las subcarpetas, debe agregar esta línea al archivo de configuración conf.py :

exclude_patterns = [''**/*admin*'']

Esa fue la parte fácil.

Mi problema era que no sabía cómo ejecutar la compilación dos veces, una con y sin los patrones de exclusión sin usar dos archivos de configuración diferentes.

No encontré una solución por mi cuenta, así que hice una pregunta aquí en SO y obtuve una respuesta :

• El archivo de configuración es solo un archivo de Python y puede contener código de Python, que se ejecutará en la compilación.
• Puede pasar parámetros (" tags ") a través de la línea de comando que se puede consultar en el archivo de configuración.

Así que tengo este patrón de exclusión en mi archivo de configuración:

exclude_patterns = [''**/*admin*'']
if tags.has(''adminmode''):
    exclude_patterns = []

Ahora puedo ejecutar la compilación sin pasar nada, lo que excluirá los archivos "admin":

make clean
make html

⇒ esta es mi documentación de usuario

... y puedo establecer la etiqueta "adminmode", que no excluirá nada:
(Sintaxis de línea de comandos de Windows)

set SPHINXOPTS=-t adminmode
make clean
make html

⇒ esta es mi documentación de administrador.

Prima:

Puedo usar la misma etiqueta para ignorar algún contenido específico en una página, tags .

Ejemplo:

regular documentation
=====================

This paragraph and its headline will always be visible.

.. only:: adminmode

        secret admin stuff
        ------------------

        This paragraph will be visible in the admin docs only.


This will (again) always be visible.

Answer 3

Las directivas only y ifconfig se pueden usar para aplicar condiciones dentro de las páginas.

No parece haber una forma sencilla de utilizar las condiciones para excluir completamente páginas enteras (archivos .rst).

Lo siguiente (en index.rst) excluye la referencia a doc2.html en el toctree en index.html cuando se genera un resultado HTML:

.. toctree::
   doc1.rst

.. only:: latex

   .. toctree::
      doc2.rst

Pero esto realmente no funciona. El archivo doc2.html todavía se genera, y se puede acceder a él a través del enlace "Siguiente tema" cuando doc1.html es el tema actual.