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.
1.2 KiB
1.2 KiB
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; requirespdflatexandmakeindex-DDPM_DOCS_HTML(default OFF) — HTML reference
cmake -B <build-dir> -DDPM_DOCS_HTML=ON
cmake --build <build-dir> --target docs
