source code layout of Sphinx doc

[marscher]

Typically the structure of a sphinx doc is:

|--doc
   |--source
      |--index.rst
   |--conf.py
   |--Makefile

The assumption made by the (usually) used Makefile is that the build directories are separated from the source. If this is not the case, incremental builds (which you usually perform locally) will try include build files as source files. This emits more and more warnings for every incremental run.
A Makefile is super useful as it provides the invocation of sphinx (you do not want to copy paste the commands every time) and it can clean up the whole build environment (e.g. delete generated files/directories). We can also a python script to invoke sphinx/clean up the build directories to remain platform agnostic.

example output, you note that the doctree within the build directory is considered a source, but is actually an output file of the previous build process.

reading sources... [ 62%] build/html/build/doctrees/nbsphinx/build/doctrees/nbsphinx/build/html/build/html/build/doctrees/nbsphinx/build/doctrees/nbsphinx/tutorials/measurement_example .. build/html/build/doctrees/nbsphinx/build/html/build/doctrees/nbsphinx/build/doctrees/nbsphinx/build/doctrees/nbsphinx/build/doctrees/nbsphinx/tutorials/GMAW_process

As a reference:
https://github.com/scipy/scipy/tree/master/doc
https://github.com/numpy/numpy/tree/main/doc
https://github.com/K3D-tools/K3D-jupyter/tree/main/docs
https://github.com/pandas-dev/pandas/tree/master/doc

[marscher]

I could also place the Makefile in devtools/doc to circumvent this problem.

[CagtayFabry]

If it makes things easier (which I guess it should) than using a makefile sounds good
I don't really have a strong opinion on where to put the build files :)

[CagtayFabry]

now that we have a Makefile, could you quickly post how to use it? @marscher
(I tried make html but ran into make: *** [Makefile:33: html] Error 1)

Should we also use this in the GitHub action? (dropping nbsphinx_execute="never" from the Makefile)

[marscher]

On 9/21/21 16:54, Cagtay Fabry wrote: now that we have a Makefile, could you quickly post how to use it? @marscher (I tried `make html` but ran into `make: *** [Makefile:33: html] Error 1`) Should we also use this in the GitHub action? (dropping `nbsphinx_execute="never"` from the Makefile)

The automatically generated Makefile of Sphinx does include all kinds of different build targets like html, pdf, ... Our Makefile only includes the html build, so you should just invoke `make` to build the docs. The other important target is `clean` to get rid of all generated files.

[marscher]

fixed by #830