apidocs
Derives the directory lists QDoc needs, and refuses a configuration that would read a vendored tree
apidocs decides what QDoc may read. It writes the generated half of the API
reference configuration, and it verifies the inputs that configuration is built
from.
It does not run QDoc for the reference. Producing the pages is building, and
the build does that: kiln apidocs invokes QDoc on the file this tool writes.
Only record runs QDoc, to make the expected output of a test fixture.
Usage
apidocs config --repo <dir> --out <file>
apidocs check --repo <dir>
apidocs project --repo <dir> --index <octomy.index> --docbook <dir> --out <api root>
apidocs coverage --repo <dir>
apidocs parity --repo <dir> --qdoc <dir> --engine <dir>
apidocs record --repo <dir> --case <dir> --qdoc <program> --qt-docs <dir>
| Mode | What it does |
|---|---|
config |
Writes the generated configuration to --out. This is what the build runs before QDoc |
check |
Verifies the same inputs and writes nothing. Prints the number of roots read to standard output |
project |
Turns QDoc's DocBook pages and its index into the markdown reference under --out |
coverage |
Counts, per library in src/libs, the .cpp files without a \class block. Writes nothing |
parity |
Compares QDoc's output with the doc engine's, and prints each difference. Exits 1 on any difference |
record |
Runs a QDoc on a test fixture and keeps its output in the fixture's expected/ folder |
| Option | Meaning |
|---|---|
--repo <dir> |
The repository root. Default: the current folder |
--out <file> |
With config: the generated configuration to write. With project: the API root |
--qdoc <path> |
With parity: QDoc's output folder, which holds docbook/ and the index. With record: the QDoc program |
--engine <dir> |
With parity: the doc engine's output folder |
--qdoc-warnings <file> |
With parity: a file with QDoc's warnings, such as the log of kiln apidocs. Default: warnings.txt in the QDoc folder |
--qdoc-root <dir>, --engine-root <dir> |
With parity: the root that each side's paths start with. Default: --repo |
--case <dir> |
With record: the fixture folder, which holds src/ |
--qt-docs <dir> |
With record: Qt's documentation folder, where QDoc reads the Qt indexes |
--define <name> |
With record, once for each: a define that QDoc's parse sees |
--quiet |
Errors only |
--verbose |
Every root left out, and every directory excluded, one per line |
--help |
The usage above |
--version |
The commit this binary was built from |
Build it with kiln build src/tools/apidocs. The examples below run it from
debug/apidocs/apidocs, its path with no output.dir
(Invoking a tool).
What it derives, and from what
The tool applies one rule with no judgment in it:
A directory is first-party when the build compiles C++ from it, and no prefix in
integration/lint/vendored-paths.txtmatches it.
Both inputs are already in the tree, and neither is a list this tool keeps:
- The product markers. A directory holding
lib.qbs,app.qbsortool.qbsis a qbs product root. That marker is what the build's own probes read, so the tool finds exactly what the build compiles. integration/lint/vendored-paths.txt. The repository's single answer to "what did we not write", shared with three other guards.
A product root enters the configuration when it holds first-party C++. A root with none is reported and left out, which is not a defect: four Khronos libraries and one tool have no first-party source at all.
Qt's own include directories come from QLibraryInfo, so no Qt path is written
down anywhere.
Reading check
$ debug/apidocs/apidocs check --repo .
188 product roots read, 5 with no first-party C++, 14 vendored directories excluded
warninglimit 1438, enabled, one spurious pattern
188
The last line is the answer on standard output. The two above it are the summary, on standard error.
Add --verbose to see which roots were left out and which directories were
excluded, one per line.
Reading coverage
$ debug/apidocs/apidocs coverage --repo .
Library Remaining Total
libllvm 4538 4541
libconstruct 381 399
...
One row for each library that has a .cpp file without a \class block. The
library with the most files to document comes first. A file counts as
documented when its text holds \class anywhere. Vendored directories are
counted too. The table goes to standard output, and a one-line total goes to
standard error.
coverage is a report, not a check: it exits 0 whatever the count. It exits 4
when --repo holds no src/libs.
coverage replaced content/doc/scripts/check_docs.sh on 2026-10-11
(script-ports §SCP-D-14). That
script stopped at the first library with no documented file, so it printed one
row.
When it fails
| Exit | Cause |
|---|---|
| 0 | The plan is sound |
| 1 | A directory named *-src or vendor* is not covered by vendored-paths.txt, or the tracked configuration broke a rule |
| 2 | The command line was wrong. Nothing was attempted |
| 3 | vendored-paths.txt is empty, or holds a prefix that is not a valid expression |
| 4 | The repository root is not one, or Qt reports no headers directory. With coverage: there is no src/libs |
Exit 1 on an uncovered vendored tree is the important one. QDoc builds one
precompiled header from every header directory it is given, so a single
vendored tree in the parse costs hundreds of class pages and the run still
exits 0. The tool refuses to write a configuration that would do that. The fix
is one line in vendored-paths.txt.
That gap is not hypothetical. llvm-src and rl-tools-src sat outside that
file for months. Both are fetched on demand, so a checkout that never fetched
has no files there, and an absent tree and an excluded tree produce the same
clean report.
Where its logic lives
The units are in src/libs/libapidocs/apidocs/ConfigPlan.{hpp,cpp}, beside the
tool, so the tool and its tests build one set of objects. main.cpp takes argv
and nothing else.
Two suites cover it. testApidocsConfigPlan drives the rule, and the
coverage count, over synthetic trees in a temporary directory. testApiReferenceConfig is a guard: it asserts
the same rule against this repository, and it runs in every test run.
See also
- Regenerate the API reference — the whole routine
- API reference — the pages this configuration produces
Reading parity
parity answers one question: does the doc engine write the same reference
as QDoc? It compares the two output folders at four levels:
| Level | The same when |
|---|---|
| L1 pages | The two folders hold the same DocBook page names |
| L2 content | The projection makes the same markdown from each pair of pages |
| L3 index | The index entries that the projection reads are equal |
| L4 warnings | The two lists of file, line and message are equal |
A fixture compared with itself, as the suite testApidocsParity does:
$ debug/apidocs/apidocs parity --repo . --qdoc test/fixtures/doc-engine/warnings/expected --engine test/fixtures/doc-engine/warnings/expected --qdoc-root @ROOT@ --engine-root @ROOT@
pages: QDoc 4, engine 4; warnings: QDoc 7, engine 7
differences: L1 pages 0, L2 content 0, L3 index 0, L4 warnings 0
Each difference follows on a line of its own, with its level, its kind, the page or the warning, and what differs.
Recording a fixture
A fixture of the doc engine is a folder under test/fixtures/doc-engine/ with
a small src/ tree. record copies it into a scratch checkout with the
tracked QDoc configuration, runs the QDoc you name, and writes the DocBook
pages, octomy.index, warnings.txt and qdoc-version.txt to the fixture's
expected/ folder. Every path of the scratch checkout becomes @ROOT@, so the
fixture holds no path of your machine. Use the QDoc that kiln apidocs runs:
debug/apidocs/apidocs record --repo . --case test/fixtures/doc-engine/one-class --qdoc ~/Qt/6.10.1/gcc_64/bin/qdoc --qt-docs ~/Qt/Docs/Qt-6.10.1