Christopher M. Punches
3b7091dc4b
The Doxygen configuration, the page list, and the docs target live in docs/, and the written documents live in docs/PROSE/, leaving the top-level file with the output paths and the add_subdirectory call. The subdirectory is given its own binary directory so that CMake's scaffolding stays out of the documentation output, which holds pdf/ and html/ and nothing else. Paths both files need are set once above the call: the child's output and cleanup and the parent's clean rule refer to the same variables.
1.3 KiB
1.3 KiB
Generating the Code Reference
When Doxygen is present, the build offers a docs target that generates the API and source reference from the documentation comments carried in the headers and sources, together with the documents in docs/PROSE/ as its pages. src/documentation.cpp declares which documents those are and in what order; docs/CMakeLists.txt configures the generator and defines the target.
One command generates it:
cmake --build <build-dir> --target docs
The finished documents land in <build-dir>/docs/:
<build-dir>/docs/pdf/dpm-core-<version>.pdf the PDF reference
<build-dir>/docs/html/index.html the HTML reference
<build-dir>/docs/tmp/ scratch space for the generators
Doxygen and LaTeX both work under docs/tmp/, and the finished document is copied up into docs/. cmake --build <build-dir> --target clean removes the whole tree.
Both formats are produced by default. Either can be turned off at configure time:
-DDPM_DOCS_PDF(default ON) — PDF reference, via Doxygen's native LaTeX output; requirespdflatexandmakeindex-DDPM_DOCS_HTML(default ON) — HTML reference
cmake -B <build-dir> -DDPM_DOCS_PDF=OFF
cmake --build <build-dir> --target docs
