Christopher M. Punches
11aad23e80
src/documentation.cpp is the documentation loading source: it carries no code and names each document that the generated reference contains, in order, by page label. The labels are declared on each markdown file's first heading. The build configuration lists the files as Doxygen inputs and nothing more, so the structure of the documentation and the mechanics of generating it are separate. The hand-maintained document index at the end of OVERVIEW.md is gone, along with the last references to markdown files by filename in the public header. The document list exists in one place. The docs target clears its output and scratch directories on every run. Doxygen keeps output files it judges unchanged, so a run over a populated scratch directory carried pages forward from earlier ones, and removed sections survived in the generated HTML and PDF after their source was edited.
32 lines
1.3 KiB
Markdown
32 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. It opens on a front page declared in `include/dpm/core.h`, followed by the module contract, then the namespace, class, and file reference.
|
|
|
|
The markdown documents in this directory are written and read on their own and stay out of the generated reference.
|
|
|
|
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
|
|
```
|
