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

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文件。该文件包括对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比赛中有相应的图案。