当使用Sphinx进行文档编写时，我应该告诉我的版本控制系统忽略哪些文件？

Question

我想开始使用Sphinx来记录我的项目。在sphinx-quickstart期间，我告诉Sphinx使用单独的源和构建目录。现在我的目录布局如下：

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

针对Sphinx项目，哪些文件应该从版本控制系统（VCS）仓库中排除（例如，由于我使用Git，我应该将什么添加到我的.gitignore文件中）？例如，我是否应该忽略docs/build/目录以便不跟踪Sphinx生成的HTML页面所做的更改?

- gotgenes

Answer 1

如果您查看Makefile的内容，您会看到以下内容：

BUILDDIR      = build

...

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

这意味着make clean只是删除了build目录，因此在版本控制方面，忽略build目录中的内容就足够了，正如你已经猜到的那样。

- jcollado

---

请注意，如果您使用 sphinx-apidoc，则 docs 目录中的几乎所有（除了 index.rst）*.rst 文件都将被生成并且可以忽略。我建议您添加一个忽略规则，例如 /docs/myproject.*。 - Bengt

但是，如果您想保留最终文件（html、pdf等）供用户使用，以便他们不必重新构建文档，则应提交 build/ 文件夹。但是，阅读文档是否需要 build/ 文件夹中的每个文件？还是有些文件可以忽略不计？ - Liam

Answer 2

如果您在GitHub上创建一个新项目，它会提供为您创建一个Python风格的.gitignore文件。该文件包括对Sphinx生成的文件的一个引用。

# Sphinx documentation
docs/_build/

注意：这里假设你在运行 sphinx-quickstart 时接受了默认设置。如果你对以下问题回答进行了调整，可能需要相应地进行调整：

1. 根目录路径：

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

   这决定了文档存储的路径。如果您将其设置为与 docs 不同的内容，则需要相应地更新 .gitignore。

2. 构建目录：

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

如果您选择了n（默认选项），那么Sphinx会在<root>/_build目录下创建构建目录（您的源文件将直接存储在<root>/下）。

如果您选择了y，那么Sphinx会在<root>/build目录下创建构建目录（您的源文件将存储在<root>/source中）。

请注意前导下划线的存在/缺失；确保您的.gitignore中相应的模式匹配。

- todofixthis