Dark-Horse-Linux/dpm-core-ng
3
0
Fork 0
Code Issues Pull Requests Actions Activity

Documentation generation produces consumable output in one command

Browse Source 
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.
This commit is contained in:
Chris Punches
2026-08-15 20:19:26 -04:00
parent 17acad2b02
commit 1cd79e79f3
8 changed files with 183 additions and 114 deletions
Download Patch File Download Diff File Expand all files Collapse all files

30
docs/DOCUMENTATION.md
View File

@@ -1,20 +1,28 @@
# 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. Two output formats are available as configure-time options:
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
Generate and compile the PDF reference:
```
cmake --build <build-dir> --target docs-pdf
```
The PDF lands at `<build-dir>/docs/latex/refman.pdf`.
With `DPM_DOCS_HTML` enabled at configure time, the `docs` target additionally produces the HTML reference in `<build-dir>/docs/html`:
```
cmake -B <build-dir> -DDPM_DOCS_HTML=ON
cmake --build <build-dir> --target docs