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

Question

我第一次尝试使用Sphinx。我正在运行sphinx-quickstart，但不理解被问到的第一个问题:

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

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

Answer 1

选择"sphinx-quickstart工具的分隔源与构建"导致两种可能的目录/文件结构布局:

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_Projectdocssourceconf.py.
   Creating file C:Your_Projectdocssourceindex.rst.
   Creating file C:Your_ProjectdocsMakefile.
   Creating file C:Your_Projectdocsmake.bat.
   Finished: An initial directory structure has been created.
   

2. 如果选择"No"(以不分离)，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_Projectdocsconf.py.
   Creating file C:Your_Projectdocsindex.rst.
   Creating file C:Your_ProjectdocsMakefile.
   Creating file C:Your_Projectdocsmake.bat.
   Finished: An initial directory structure has been created.
   

我怎么知道该选哪一个?

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