Christopher M. Punches
1cd79e79f3
Building the docs target now generates the reference and leaves finished documents in the build tree's docs directory: pdf/ holds the compiled PDF, html/ holds the browsable reference when that format is enabled. Doxygen and LaTeX work under docs/tmp/, which clean removes along with the rest of the tree. The reference has a front page and a structure. The markdown documents in docs/ are part of the input, OVERVIEW.md becomes the landing page, and the rest follow as chapters ahead of the namespace, class, and file reference. The module contract, previously a plain comment block invisible to Doxygen, is a page in its own right. Struct and enum members throughout the headers carry documentation, on their own lines above what they describe.
30 lines
1.2 KiB
Markdown
30 lines
1.2 KiB
Markdown
# Generating the Code Reference
|
|
|
|
When Doxygen is present, the build offers a `docs` target that produces the reference from the documentation comments carried in the headers and sources, together with the markdown documents in `docs/`. OVERVIEW.md becomes its front page, and DESIGN.md, MODULES.md, CONSUMERS.md, BUILD.md, and this file follow as chapters ahead of the namespace, class, and file 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.
|
|
|
|
Two output formats are available as configure-time options:
|
|
|
|
- **`-DDPM_DOCS_PDF`** (default ON) — PDF reference, via Doxygen's native LaTeX output; requires `pdflatex` and `makeindex`
|
|
- **`-DDPM_DOCS_HTML`** (default OFF) — HTML reference
|
|
|
|
```
|
|
cmake -B <build-dir> -DDPM_DOCS_HTML=ON
|
|
cmake --build <build-dir> --target docs
|
|
```
|
