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?
Put simply the option "Separate sources from build" of the sphinx-quickstart
tool leads to 2 possible directory/file structure layouts:
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.
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.