“分离源目录和构建目录”是什么意思？

Question

我是第一次尝试使用 Sphinx。我正在运行

sphinx-quickstart

，但不明白提出的第一个问题：

> Separate source and build directories (y/n) [n]: 这是什么意思？这些目录分开与否有什么区别呢？我怎么知道该选择哪一个？

Answer 1

简单地说，

sphinx-quickstart工具的选项

“从构建中分离源”

会导致 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

    工具的摘录，选择“否”将源与构建分开：

   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

 分开。可以说，将文件分开可以使大型项目中的事情更有条理。唯一的缺点是您将拥有更多目录，一开始这可能看起来令人困惑，但从长远来看，增加的分离往往是值得的。