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

Posted 2021-05-03

我想开始使用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页面中的更改？

答案

如果你看一下Makefile的内容，你会看到如下内容：

BUILDDIR      = build

...

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

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

另一答案

如果您在GitHub上创建一个新项目，它将为您创建一个Python风格的.gitignore文件。此文件包含one reference到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中的相应模式匹配。