Document several language standards
A C++ library may offer more API with C++20 than with C++17, and a Python package may guard
definitions with sys.version_info. cpdocs documents each language standard or version you list and
marks every declaration and overload with the standards it exists in.
Listing the standards
languages in cpdocs.yml is a Keyso configuration space.
cpdocs expands it into concrete language configurations, runs build.feature-sets once for each,
and builds every variant of each:
languages:
cxx:
_nested:
standard: [17, 20, 23]
build:
feature-sets: >
cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
-DCMAKE_CXX_STANDARD="{{cxx.standard}}"
-DCPDOCS_FEATURE_SETS_OUTPUT="{{output-file}}"
build: >
cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
-DCMAKE_CXX_STANDARD="{{cxx.standard}}"
-DCPDOCS_FEATURE_SET="{{feature-set}}"
-DCPDOCS_MANIFEST_OUTPUT="{{output-file}}"
Each value reaches the hooks as a dotted placeholder, such as {{cxx.standard}}, {{c.standard}},
{{fortran.standard}}, {{python.version}} or {{rust.edition}}. The build system decides how
to apply it; cpdocs does not turn values into compiler flags.
_product combines several languages in every combination, and _set lists explicit pairs:
languages:
_set:
- cxx: {standard: 17}
python: {version: "3.11"}
- cxx: {standard: 23}
python: {version: "3.12"}
How availability is found
Availability comes from the API extracted for each language configuration and variant; no cpdocs-specific annotations are needed.
- C and C++ projects use their usual
#if __cplusplusor__STDC_VERSION__guards. Clang parses the headers with the standard and flags the manifest gives. - Python guards written with
sys.version_info, includingsys.version_info[:2],.majorand.minor, imported aliases,elifandelseand simple boolean combinations, are evaluated for the configuredpython.versionwithout importing the package. Definitions under a guard cpdocs cannot evaluate are left out. The source is parsed with the Python running cpdocs, so syntax newer than that interpreter needs a newer one. - Fortran and Rust follow the API their extractor finds for each configuration.
The reference lists the standards of each declaration and overload separately from its variants. Only configurations that were analysed are shown: documenting C++20 and C++23 does not claim C++26, and presence in the API does not claim that a feature was tested.
The cpp-standards example builds C++17, C++20 and C++23 from one configuration, with functions added and removed between standards and standard-dependent overloads.