Christopher M. Punches
38bd9314cc
The project version moves to 1.0.0, which the library soname, the reported version, the test expectations, and the generated document filename all derive from. SOVERSION now matches the major version. The generated reference is built from the source and its documentation comments alone. Prose from docs/ was briefly part of the input and is removed: development notes are written and read on their own, and a generator that reproduces them adds nothing. The reference opens on a front page declared in the public header, followed by the module contract. One target builds it. Both PDF and HTML are produced by default, the finished documents land in the build tree under docs/pdf and docs/html, and the generators work in docs/tmp. The internal namespace is dpm_core, matching the artifact name as closely as a C++ identifier permits.
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. 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; requirespdflatexandmakeindex-DDPM_DOCS_HTML(default ON) — HTML reference
cmake -B <build-dir> -DDPM_DOCS_PDF=OFF
cmake --build <build-dir> --target docs
