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?

score 22 · Accepted Answer · answered Mar 05 '12 at 16:53

22

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 Mar 05 '12 at 16:53

jcollado

39,419
8
102
133

1

Note that if you use [sphinx-apidoc](http://sphinx-doc.org/man/sphinx-apidoc.html), almost all (except `index.rst`) `*.rst` files in `docs` will get generated and can be ignored, too. I would suggest an ignore rule like `/docs/myproject.*`. – Bengt Oct 15 '13 at 04:43
9

But if you want to preserve the final files (html, pdf, etc.) for users so they don't have to rebuild the documentation, then build/ should be committed, but is every file in build/ needed to read the documentation, or can some be ignored? – Liam Apr 25 '15 at 13:09

todofixthis · Answer 2 · 2018-03-06T19:41:44.683

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.

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

2 Answers2