cpdocs.yml
docs/cpdocs.yml contains only cpdocs orchestration and presentation policy. The build system owns
all project semantics: features, valid feature combinations, generated code, targets, headers and
sources.
The file is read as Korml, the JSON-shaped subset of YAML:
mappings, sequences, scalars, comments, flow collections and block scalars. Anchors, aliases, tags,
complex keys and duplicate keys are errors. Every scalar is text, so versions: [1.10] names the
version 1.10 and does not become the number 1.1; cpdocs decodes the few values it needs as numbers,
such as the bounds of a Keyso _interval.
A minimal configuration is:
contract: 3
build:
feature-sets: >
cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
-DCPDOCS_FEATURE_SETS_OUTPUT="{{output-file}}"
build: >
cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
-DCPDOCS_FEATURE_SET="{{feature-set}}"
-DCPDOCS_MANIFEST_OUTPUT="{{output-file}}"
versions: [main, v2.0.0, v1.0.0]
The two hooks are the whole build-system interface. build.feature-sets runs once per version and
language configuration and lists the build variants; build.build runs once for every variant it
lists. See the build-system contract.
| Key | Default | Meaning |
|---|---|---|
build.feature-sets |
required | hook that lists the build variants in feature-sets.json |
build.build |
required | hook that builds the variant in feature-set.json and describes it in manifest.json |
languages |
none | Keyso space of language standards, see Document several language standards |
versions |
[main] |
exact branch/tag names to document, in publication/default order |
site.index |
docs/api/index.md |
introduction of the API reference |
site.copyright |
project developers | footer text |
site.project-docs |
auto |
URL of the project website |
site.theme.logo |
none | image shown before the project name in the top bar |
site.theme.favicon |
site.theme.logo |
image used as the favicon |
site.theme.stylesheet |
none | CSS file loaded after the cpdocs stylesheet |
site.theme.colors.light, site.theme.colors.dark |
cpdocs colours | colours of each scheme, see Theme |
api.hide.cpp-namespaces |
none | glob patterns of C++ namespaces omitted with their contents |
api.hide.python-modules |
private |
private hides modules beginning with _ from the API, while their files stay in the file hierarchy; none shows them |
checks.undocumented |
ignore |
warn or fail when public entities have no documentation |
checks.broken-references |
warn |
ignore, warn or fail for unknown @apidocs targets |
The same current cpdocs.yml orchestration commands are used for every checkout in versions; old tags do not need to carry their own cpdocs configuration.
The first entry in versions is the default version of the published API site.
For local ProperDocs serving, the current working tree is temporarily placed first so uncommitted
changes are visible.
Theme
site.theme presents the API site in the project's colours and with its logo, so that the
reference matches the project documentation it links back to. Every key is optional; without
site.theme the site keeps the cpdocs look.
site:
theme:
logo: share/brand/icon.svg
stylesheet: docs/api.css
colors:
light:
accent: "#266c7c"
accent-2: "#eba333"
selected: "#e6f0f2"
dark:
accent: "#65a9ba"
accent-2: "#eba333"
on-accent: "#0d1f24"
selected: "#1d3940"
Paths are relative to the project root. The logo and the favicon are SVG, PNG, ICO, WebP, JPEG or
GIF images; without a favicon, the logo serves as one. The theme is taken from the current tree for
every entry of versions, so older versions are presented the way the project looks today.
The API site has a light and a dark scheme, and the reader switches between them. colors.light
and colors.dark each set any of the colours below; a colour that a scheme does not set keeps its
cpdocs value in that scheme. Values are hexadecimal, #rgb, #rgba, #rrggbb or #rrggbbaa, and
must be quoted, because an unquoted # starts a comment.
| Colour | Used for |
|---|---|
accent |
links, heading rules, the current outline entry and the project documentation button |
accent-2 |
secondary rules, such as the marks of section headings and the feature-set cards |
on-accent |
text on the accent, such as the label of the project documentation button |
background |
page background |
foreground |
body text |
muted |
secondary text |
border |
borders and separators |
soft |
background of hovered and highlighted areas |
selected |
background of selected entries |
stylesheet is for anything the colours do not cover. cpdocs writes the colours and then the
stylesheet into assets/cpdocs-theme.css, which every page loads after the cpdocs stylesheet. The
class names of the cpdocs pages are not a stable interface; rules on them may need adjusting when
cpdocs changes.