"Separate source and build directories" 是什么意思？

Question

我是第一次尝试使用 Sphinx。我是运行 sphinx-quickstart，但不明白被问的第一个问题：

> Separate source and build directories (y/n) [n]:

这是什么意思？这些目录是否分开有什么区别？我怎么知道选择哪一个？

Answer 1

简单地使用 sphinx-quickstart 工具的选项 “从构建中分离来源” 会导致 2 种可能的 directory/file 结构布局：

如果你选择“是”（分开），你会得到一个build目录和一个source目录：

生成的.rst文件和conf.py放在source目录下（之后你写的任何.rst文件也应该放在那里）。 Sphinx 将从 reStructuredText 源文件生成的最终文档文件（例如 HTML）放置在 build 目录中。

C:.
│   make.bat
│   Makefile
│
├───build
└───source
    │   conf.py
    │   index.rst
    │
    ├───_static
    └───_templates

以下是运行使 sphinx-quickstart 工具选择“是”以将来源与构建分开的摘录：

Creating file C:\Your_Project\docs\source\conf.py.
Creating file C:\Your_Project\docs\source\index.rst.
Creating file C:\Your_Project\docs\Makefile.
Creating file C:\Your_Project\docs\make.bat.

Finished: An initial directory structure has been created.

如果选择“否”（不分离），则不会创建source目录，因此放置在source目录中的内容选择“分离” sources" 选项将被放置在运行 sphinx-quickstart.

所在的基本目录中

构建目录也会略有不同，现在名称中有下划线 _build：

C:.
│   conf.py
│   index.rst
│   make.bat
│   Makefile
│
├───_build
├───_static
└───_templates

以下是运行使用 sphinx-quickstart 工具选择“否”以将源与构建分开的摘录：

Separate source and build directories (y/n) [n]: 

Creating file C:\Your_Project\docs\conf.py.
Creating file C:\Your_Project\docs\index.rst.
Creating file C:\Your_Project\docs\Makefile.
Creating file C:\Your_Project\docs\make.bat.

Finished: An initial directory structure has been created.

How do I know which one to choose?

我见过的最普遍的选择是选择将 sources 与 build 分开。可以说，将文件分开可以使大型项目中的事情更有条理。唯一的缺点是你会有更多的目录，一开始可能看起来很混乱，但增加的分离在较长的运行.

中往往是值得的。

"Separate source and build directories" 是什么意思？

What does "Separate source and build directories" mean?

python

python-3.x

python-sphinx