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

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工具的摘录，选择“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. 将文件分开可以说使大型项目中的事情更有条理。唯一的缺点是您将拥有更多的目录，这乍一看似乎令人困惑，但从长远来看，增加的分离往往是值得的。