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

Release version 1.0.0; keep generated documentation source-derived

Browse Source 
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.
This commit is contained in:
Chris Punches
2026-08-15 20:45:47 -04:00
parent 1cd79e79f3
commit 38bd9314cc
9 changed files with 48 additions and 35 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/DOCUMENTATION.md
View File

@@ -1,6 +1,8 @@
# 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.
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:
@@ -18,12 +20,12 @@ The finished documents land in `<build-dir>/docs/`:
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:
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 OFF) — HTML reference
- **`-DDPM_DOCS_HTML`** (default ON) — HTML reference
```
cmake -B <build-dir> -DDPM_DOCS_HTML=ON
cmake -B <build-dir> -DDPM_DOCS_PDF=OFF
cmake --build <build-dir> --target docs
```