This is for use with the currently not maintained Sphinx-Toolchain and, as such, does not reflect the current structure of generated files. However, it will be kept here for legacy and reference.
<PROJECT>
├───doc
│ └───<tbd.>
├───out
│ ├───doc
│ │ └───<PROJECT>
│ │ ├───.doctrees
│ │ │ ├───doc
│ │ │ │ └───<PROJECT>
│ │ │ │ └───src
│ │ │ │ └───exhale
│ │ │ │ └───<...doctree>
│ │ │ ├───environment.pickle
│ │ │ └───index.doctree
│ │ ├───_sources
│ │ │ ├───doc
│ │ │ │ └───<PROJECT>
│ │ │ │ └───src
│ │ │ │ └───exhale
│ │ │ │ └───<...rst.txt>
│ │ │ └───index.rst.txt
│ │ ├───_static
│ │ │ └───<...>
│ │ ├───doc
│ │ │ └───<PROJECT>
│ │ │ └───src
│ │ │ └───exhale
│ │ │ └───<...html>
│ │ ├───src
│ │ │ ├───doxygen
│ │ │ │ └───xml
│ │ │ │ └───<...>
│ │ │ └───exhale
│ │ │ ├───<...rst>
│ │ │ └───<...rst.include>
│ │ ├───genindex.html
│ │ ├───index.html
│ │ ├───search.html
│ │ ├───searchindex.js
│ │ └───<...>
│ ├───conf.py
│ └───index.rst
├───sourcetodoc
│ └───helpers.py
├───submodules
│ └───doxygen-awesome-css (submodule)
| └───<...>
└───main.py
The out directory and all of its contents are automatically generated after running main.py. out
should generally contain everything generated by the toolchain.
conf.py and ìndex.rst are the "main config files" for sphinx. If any manual modifications are desired,
Sphinx must be executed manually with sphinx-build -b html . <PATH TO out>, because running main.py again
will reset them.
doc contains the generated documentation, which should be most of, if not all, of the toolchain's output.
Here, it first contains a directory with the input project's name. This way doc is intended as a collection of
documentation of potentially multiple input projects. An option to swap the order of these directories will be
added to better suite the use case of simply generating a doc folder to paste right into the input project.
The innermost of these two directory serves as the root directory for the generated documentation by
containing the main page (index.html), the alphabetical index page (genindex.html) and the search page
(search.html + searchindex.js). Additionally, it also contains various further directories with pages
linked in/accessible via index.html, but also various intermediate artifacts (doxygen, breathe, rst and
rst.txt files) generated within the toolchain. Unfortunately, this whole "intermediate situation" is a little
bit convoluted, because some of the tools do not allow to specify all output paths for their intermediate
artifacts. By default, these artefacts are not deleted automatically, because they could serve a further
purpose not considered within this toolchain (yet) or may be edited to the users' liking before manually
running Sphinx again.
.doctrees contains doxygen's intermediate files (doctrees) and mimics the hierarchy within out to
src/exhale. doxygen's XML output is located in src/doxygen/xml.
src/exhale contains the .rst and .rst.include files generated by exhale.
_sources also follows the structure until src/exhale, but contains Sphinx intermediate text files
(.rst.txt). This structure is seen once again, but from the perspective of out/doc/<PROJECT> starting
from doc and containing the final .html files, representing the doxygen XML output, generated by Sphinx.
Finally, _static contains style information mostly dependent on the selected Sphinx HTML template.