Jakie pliki należy przekazać mojemu systemowi VCS do zignorowania podczas używania Sphinx do dokumentacji?

Question

Chcę zacząć używać Sphinx do dokumentowania mojego projektu. Powiedziałem Sphinxowi, aby używał oddzielnych katalogów źródłowych i kompilacji podczas sphinx-quickstart. Teraz mój układ katalogów jest następująca:

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

Jakie pliki powinny być wyłączone z repozytorium VCS dla projektu Sphinx (czyli odkąd używam Git, co należy dodać do mojego pliku .gitignore)? Na przykład, czy powinienem zignorować katalog docs/build/, aby zmiany w stronach HTML generowanych przez Sphinx nie były śledzone?

Answer 1

Jeśli spojrzeć na zawartość Makefile zobaczysz coś w następujący sposób:

BUILDDIR  = build 

... 

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

Oznacza to, że make clean tylko usuwa katalog build tak, w odniesieniu do kontroli wersji, ignorując zawartość Katalog build powinien wystarczyć, tak jak już podejrzewasz.

Answer 2

Jeśli utworzysz nowy projekt na GitHub, zaoferuje ci on stworzenie pliku o smaku Pythona .gitignore. Plik ten zawiera one reference do Sphinx generowanych plików:

# Sphinx documentation 
docs/_build/ 

Uwaga: ta zakłada, że ​​akceptujesz ustawienia domyślne po uruchomieniu sphinx-quickstart. Być może trzeba dostosować je w zależności od sposobu odpowiedzi na te pytania: ścieżkę

1. root:

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

   ta określa ścieżkę, w której przechowywana jest dokumentacja. Jeśli zrobiłeś coś innego niż docs, musisz odpowiednio zaktualizować .gitignore.

2. katalog budowy:

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

   Jeśli odpowiedziałeś n (ustawienie domyślne), a następnie Sphinx stworzy katalog budowy w <root>/_build (pliki źródłowe zostaną zapisane bezpośrednio pod <root>/).

   Jeśli odpowiedziałeś y, wówczas Sphinx utworzy katalog kompilacji pod numerem <root>/build (twoje pliki źródłowe będą przechowywane w <root>/source).

   Uwaga na obecność/brak wiodącego podkreślenia; upewnij się, że odpowiadający wzór w twoim .gitignore jest zgodny.