Question

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

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

应从Sphinx项目的VCS存储库中排除哪些文件（即，因为我使用Git，我应该将哪些文件添加到我的.gitignore文件中）？例如，我是否应该忽略docs/build/目录，以便不跟踪从Sphinx生成的HTML页面中的更改？

Answer 1

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

BUILDDIR      = build

...

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

这意味着make clean只删除build目录，因此，就版本控制而言，忽略build目录的内容应该足够您已经怀疑了。

Answer 2

如果您在GitHub上创建一个新项目，它将为您创建一个Python风格的.gitignore文件。此文件包含one reference到Sphinx生成的文件：

# Sphinx documentation
docs/_build/

注意：这假定您在运行sphinx-quickstart时接受默认值。您可能需要根据您回答这些问题的方式进行调整：

根路径：
```
Enter the root path for documentation.
> Root path for the documentation [.]:
```
这确定了存储文档的路径。如果您使用docs以外的其他内容，那么您需要相应地更新.gitignore。
构建目录：
```
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中的相应模式匹配。

在使用Sphinx文档时，我应该告诉VCS忽略哪些文件？

2 个答案: