Which files should I tell my VCS to ignore when using Sphinx for documentation?
If you create a new project on GitHub, it will offer to create a Python-flavored .gitignore
file for you. This file includes one reference to Sphinx-generated files:
# Sphinx documentation
docs/_build/
Note: This assumes that you accept the defaults when you run sphinx-quickstart
. You may need to adjust it depending on how you answered these questions:
Root path:
Enter the root path for documentation. > Root path for the documentation [.]:
This determines the path where documentation is stored. If you made it something other than
docs
, then you'll need to update.gitignore
accordingly.Build directory:
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]:
If you answered
n
(default), then Sphinx will create the build directory at<root>/_build
(your source files will be stored directly under<root>/
).If you answered
y
, then Sphinx will create the build directory at<root>/build
(your source files will be stored in<root>/source
).Note the presence/absence of the leading underscore; make sure the corresponding pattern in your
.gitignore
matches.
If you take a look at the contents of Makefile
you'll see something as follows:
BUILDDIR = build
...
clean:
-rm -rf $(BUILDDIR)/*
This means that make clean
just removes the build
directory so, with regard to version control, ignoring the contents of the build
directory should be enough as you already suspected.