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.
30 lines
1.3 KiB
Markdown
30 lines
1.3 KiB
Markdown
# Generating the Code Reference {#documentation}
|
|
|
|
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; requires `pdflatex` and `makeindex`
|
|
- **`-DDPM_DOCS_HTML`** (default ON) — HTML reference
|
|
|
|
```
|
|
cmake -B <build-dir> -DDPM_DOCS_PDF=OFF
|
|
cmake --build <build-dir> --target docs
|
|
```
|
