¿Qué archivos debo decirle a mi VCS que ignore cuando use Sphinx para la documentación?

Question

Quiero comenzar a usar Sphinx para documentar mi proyecto. Le dije a Sphinx que use directorios de origen y compilación separados durante sphinx-quickstart. Ahora mi estructura de directorios es la siguiente:

MyProject/ 
    myproject/ 
     __init__.py 
     mymodule.py 
    docs/ 
     source/ 
      .static/ 
      .templates/ 
      conf.py 
      index.rst 
     build/ 
     Makefile 

qué archivos deben ser excluidos de un repositorio VCS para un proyecto Sphinx (es decir, desde que uso de Git, lo que debería añadir a mi archivo .gitignore)? Por ejemplo, ¿debería ignorar el directorio docs/build/ para que no se rastreen los cambios en las páginas HTML generadas desde Sphinx?

Answer 1

Si se echa un vistazo a los contenidos de Makefile verá algo de la siguiente manera:

BUILDDIR  = build 

... 

clean: 
    -rm -rf $(BUILDDIR)/* 

Esto significa que make clean sólo elimina el directorio build así, en lo que respecta al control de versiones, haciendo caso omiso de los contenidos de el directorio build debería ser suficiente como usted ya sospechaba.

Answer 2

Si creas un nuevo proyecto en GitHub, te ofrecerá crear un archivo .gitignore con Python con sabor para ti. Este archivo incluye one reference a los archivos generados por Sphinx:

# Sphinx documentation 
docs/_build/ 

Nota: Esto supone que acepta los valores por defecto cuando se ejecuta sphinx-quickstart. Puede que tenga que ajustar en función de cómo respondido a estas preguntas: ¿senda

1. Raíz:

   Enter the root path for documentation. 
   > Root path for the documentation [.]: 
   

   Esto determina la ruta en la que se almacena la documentación. Si lo hizo algo distinto de docs, entonces deberá actualizar .gitignore en consecuencia.

2. directorio de construcción:

   You have two options for placing the build directory for Sphinx output. 
   Either, you use a directory "_build" within the root path, or you separate 
   "source" and "build" directories within the root path. 
   > Separate source and build directories (y/n) [n]: 
   

   Si su respuesta n (por defecto), entonces Sphinx creará el directorio de construcción en <root>/_build (los archivos de origen se almacenarán directamente bajo <root>/).

   Si respondió y, Sphinx creará el directorio de compilación en <root>/build (sus archivos de origen se almacenarán en <root>/source).

   Tenga en cuenta la presencia/ausencia del subrayado inicial; asegúrese de que coincida el patrón correspondiente en su .gitignore.