Document generated headers
Generated headers stay generated: they are not checked in for cpdocs. cpdocs reads headers only after the build hook has returned, so the hook only has to run the generators first, and the manifest names where their output lands.
Run the generators in the build hook
Headers written by configure_file exist as soon as CMake has configured the build. Headers written
by a build target, such as a code generator, need that target built. The build hook does both:
build:
build: >
cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
-DCPDOCS_FEATURE_SET="{{feature-set}}"
-DCPDOCS_MANIFEST_OUTPUT="{{output-file}}"
&& cmake --build "{{tmpdir}}" --target acme-generated-headers
Building only the generator target is enough; cpdocs does not need the library itself compiled.
Name the output directory in the manifest
The generated include directory is an API root of its own, marked generated, next to the
checked-in one:
{
"id": "acme",
"language": "cpp",
"api": [
{"path": "/src/include"},
{"path": "/src/build/generated/include", "generated": true}
],
"parse": {"include": ["/src/include", "/src/build/generated/include"]}
}
Both directories go on the include path, so a checked-in header can include a generated one, as it would in an ordinary build.
What the reference shows
Generated declarations are documented like any other, from the comments the generator writes, and
each generated header appears at its include path, such as acme/status.hpp, marked as generated by
the build.
The generated-cpp example generates acme/version.hpp from a template at configure time and
acme/status.hpp from a table of status codes at build time; its checked-in header includes both.