“单独的源和构建目录”是什么意思？

如何解决“单独的源和构建目录”是什么意思？

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

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

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

解决方法

简单地说，sphinx-quickstart 工具的 “Separate sources from build” 选项会导致 2 种可能的目录/文件结构布局：

1. 如果您选择“是”（分隔），您将获得一个 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.
   

2. 如果您选择“否”（不分离），则不会创建 source 目录，因此放置在 source 目录中的内容将选择“分离源”选项而是放置在您运行 sphinx-quickstart 的基本目录中。

   此外，构建目录将略有不同，现在名称中带有下划线 _build：

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

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

   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.
   

我怎么知道选择哪一个？

我见过的普遍选择是选择将 sources 与 build 分开。将文件分开可以说使大型项目中的事情更有条理。唯一的缺点是您将拥有更多的目录，乍一看可能会让人感到困惑，但从长远来看，增加分离往往是值得的。