What does "Separate source and build directories" mean?

Question

I am trying to use Sphinx for the first time. I am running sphinx-quickstart, but don't understand the first question being asked:

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

What does this mean? What difference does it make whether these directories are separated or not? How do I know which one to choose?

Answer 1

Put simply the option "Separate sources from build" of the sphinx-quickstart tool leads to 2 possible directory/file structure layouts:

1. If you choose "Yes" (to separate), you 'll get one build directory and one source directory:

   The generated .rst files and conf.py are placed in the source directory (afterwards any .rst files you write should also be placed there). The final documentation files (HTML for example) that Sphinx will generate from the reStructuredText source files are placed in the build directory.

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

   Here's an excerpt of running the sphinx-quickstart tool choosing "YES" to separate sources from build:

   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. If you choose "No" (to not separate), the source directory is not created so the contents that were placed in the source directory choosing the "separate sources" option will instead be placed in the base directory from where you run sphinx-quickstart.

   Also the build directory will be slightly different now having an underscore _build in the name:

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

   Here's an excerpt of running the sphinx-quickstart tool choosing "NO" to separate sources from build:

   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?

The prevalent option I've seen is choosing to separate sources from build. Keeping the files separate arguably makes things more organized in larger projects. The only drawback is that you'll have more directories, which may seem confusing at first, but the increased separation tends to be worth it in the long run.