Which files should I tell my VCS to ignore when using Sphinx for documentation?

Question

I want to start using Sphinx to document my project. I told Sphinx to use separate source and build directories during sphinx-quickstart. Now my directory layout is the following:

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

Which files should be excluded from a VCS repository for a Sphinx project (i.e., since I use Git, what should I add to my .gitignore file)? For example, should I ignore the docs/build/ directory so that changes in the HTML pages generated from Sphinx aren’t tracked?

Asked By: gotgenes

||

Source

Answer 1

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.

Answered By: jcollado

Answer 2

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.

Answered By: todofixthis

Which files should I tell my VCS to ignore when using Sphinx for documentation?

Question:

Answers: