cpdocs 0.1.0__tar.gz → 0.2.0__tar.gz

{cpdocs-0.1.0 → cpdocs-0.2.0}/.github/workflows/docs.yml

@@ -42,11 +42,10 @@ jobs:
       - uses: astral-sh/setup-uv@v6
       - name: Install toolchain for the C and C++ examples
         run: sudo apt-get install -y --no-install-recommends clang cmake ninja-build
+      - name: Install toolchain for the Rust example
+        run: rustup toolchain install nightly-2026-10-01 --profile minimal
       - name: Build documentation
         run: uv run properdocs build --strict
-      # Each example is published below examples/<name>/ as its own versioned site.
-      - name: Build example sites
-        run: uv run python tools/build_example_sites.py --output build/site/examples
       - uses: actions/upload-pages-artifact@v3
         with:
           path: build/site

{cpdocs-0.1.0 → cpdocs-0.2.0}/.github/workflows/test.yml

@@ -14,6 +14,8 @@ jobs:
       - uses: astral-sh/setup-uv@v6
       - name: Install toolchain for the C and C++ examples
         run: sudo apt-get install -y --no-install-recommends clang cmake ninja-build
+      - name: Install toolchain for the Rust example
+        run: rustup toolchain install nightly-2026-10-01 --profile minimal
       - name: Lint
         run: uv run ruff check && uv run ruff format --check
       - name: Test

{cpdocs-0.1.0 → cpdocs-0.2.0}/PKG-INFO

@@ -1,13 +1,12 @@
 Metadata-Version: 2.5
 Name: cpdocs
-Version: 0.1.0
-Summary: Semantic, versioned API documentation for C, C++, Python and Rust projects
+Version: 0.2.0
+Summary: Semantic, versioned API documentation for C, C++, CUDA, HIP, Fortran, Python and Rust projects
 Project-URL: Source, https://github.com/ambhora/cpdocs
 Author-email: Jayesh Badwaik <j.badwaik@fz-juelich.de>
 License-Expression: Apache-2.0
 Requires-Python: >=3.11
 Requires-Dist: markdown-it-py>=3
-Requires-Dist: packaging>=24
 Requires-Dist: pygments>=2.17
 Requires-Dist: pyyaml>=6
 Provides-Extra: properdocs
@@ -20,16 +19,19 @@ SPDX-License-Identifier: Apache-2.0
 -->
 # cpdocs
 
-cpdocs generates semantic, versioned API documentation for C, C++, Python and Rust projects.
+cpdocs generates semantic, versioned API documentation for C, C++, CUDA, HIP, Fortran, Python and Rust projects.
 
-It asks the project's build system, through a small JSON contract, which variants of the API exist
-and how to read each of them. It then extracts every variant, Clang for C and C++, `ast` for Python
-and rustdoc JSON for Rust, merges them into one reference, and publishes one version per configured
-branch and tag. A CMake adapter ships with cpdocs; other build systems implement the same contract.
+It asks the project's build system, through a small JSON contract, for the concrete feature sets to
+document. It builds each feature set independently, consumes the resulting manifest, extracts the API
+with Clang for C-family languages, source modules for Fortran, `ast` for Python or rustdoc JSON for
+Rust, and merges the results. Implementation files from the manifest are kept in the file hierarchy
+without becoming API entities.
+Feature-set availability and API language are tracked independently. The versions
+to publish are an explicit ordered list in `cpdocs.yml`.
 
 ```console
 cpdocs build          # document the working tree into build/cpdocs/current
-cpdocs versions       # document the configured branches and tags
+cpdocs versions       # document the configured versions
 properdocs build      # project website with the versioned API mounted
 ```
 
@@ -45,4 +47,5 @@ uv run pytest
 uv run ruff check && uv run ruff format --check
 ```
 
-The C and C++ tests need `clang++`, `cmake` and `ninja`; they are skipped when these are missing.
+The C and C++ tests need `clang++`, `cmake` and `ninja`. Building the Rust example/site also needs
+the nightly toolchain pinned by `examples/rust-basic/rust-toolchain.toml`.

cpdocs-0.2.0/docs/cpdocs.yml

@@ -0,0 +1,17 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+contract: 3
+
+build:
+  feature-sets: >
+    "{{python}}" -m cpdocs manifest python feature-sets
+    --source "{{source}}" --output "{{output-file}}"
+  build: >
+    "{{python}}" -m cpdocs manifest python build
+    --source "{{source}}" --feature-set "{{feature-set}}" --output "{{output-file}}"
+    --package cpdocs --package-source src/cpdocs
+
+versions: [main]
+
+site:
+  copyright: Copyright © cpdocs developers · Apache-2.0

cpdocs-0.2.0/docs/web/examples/index.md

@@ -0,0 +1,24 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Examples
+
+Every directory in `examples/` is a standalone project with its own `docs/cpdocs.yml` and
+ProperDocs site. The test suite builds them, and the root ProperDocs site mounts each example directly during its
+own build. Each example site is versioned with its explicit `versions:` list.
+
+| Example | Shows | Site |
+| --- | --- | --- |
+| `basic-cpp` | one compiled C++ library | [basic-cpp](basic-cpp/) |
+| `cpp-templates` | specializations, concepts, requires-clauses, SFINAE and deduction guides | [cpp-templates](cpp-templates/) |
+| `cpp-features` | feature-dependent API across three feature sets; the same project through `tools/minibuild.py` | [cpp-features](cpp-features/) |
+| `generated-cpp` | headers generated during the build | [generated-cpp](generated-cpp/) |
+| `c-basic` | a C library | [c-basic](c-basic/) |
+| `mixed` | a C++ unit and a Python unit in one project | [mixed](mixed/) |
+| `fortran-basic` | a Fortran module plus an implementation-only source file | [fortran-basic](fortran-basic/) |
+| `python-basic` | a plain Python package, answered by `cpdocs manifest python` | [python-basic](python-basic/) |
+| `rust-basic` | Cargo features plus nightly rustdoc JSON, with private implementation source still browseable | [rust-basic](rust-basic/) |
+
+There is no separate example-site build step. Both `properdocs build` and `properdocs serve` build
+these sites directly at `examples/<name>/`; during `serve`, they use the checked-out working tree.

cpdocs-0.2.0/docs/web/explanation/architecture.md

@@ -0,0 +1,23 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Architecture
+
+cpdocs is a pipeline with a single boundary to the outside:
+
+1. **Contract.** The build system enumerates concrete feature sets and builds one selected feature set at a time.
+   cpdocs only reads the resulting JSON files.
+2. **Extraction.** Each unit of each feature set becomes an API graph. The manifest's semantic
+   language (`c`, `cpp`, `cuda`, `hip`, ...) is kept separate from the parser frontend used to
+   extract it. Clang handles the current C-family frontends, `ast` handles Python, and rustdoc JSON
+   handles Rust.
+3. **Merge.** The graphs of all units of a feature set are combined; feature-set graphs are then
+   merged. Identical definitions accumulate feature-set availability, while definitions in different
+   semantic languages remain distinct API entries.
+4. **Rendering.** The merged graph becomes a standalone HTML site. Versions are rendered
+   independently and joined by `versions.json`.
+
+The API graph, @apidocs::cpdocs.model.ApiGraph, is the only interface between the stages; the
+whole pipeline for one ref is @apidocs::cpdocs.build.build_graph. Adding a language means adding an
+extractor that produces it; adding a build system means implementing the contract.

cpdocs-0.2.0/docs/web/explanation/feature-sets.md

@@ -0,0 +1,21 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Why the build system owns feature sets
+
+Only the build system knows which feature combinations are valid, which generators must run, and
+which headers are public in a concrete configuration. Repeating that knowledge in cpdocs would
+create a second configuration language that inevitably drifts from the project.
+
+cpdocs therefore consumes an enumerable list of **unnamed feature sets** and passes one selection
+back to the build system at a time. It uses the feature list only to record availability.
+
+Programming language is a separate property of the manifest unit. A `gpu` feature can expose a
+`CUDA` unit; several different feature sets can expose the same CUDA definition; and a C++
+definition can be available in every feature set. During merging, identical definitions accumulate
+feature-set availability, while definitions with different semantic languages remain distinct.
+
+Version policy is equally explicit: `versions:` is simply the ordered list of Git branches/tags to
+publish. There is no second selector language for branches, tags, ranges, aliases, or feature-set
+policies.

{cpdocs-0.1.0 → cpdocs-0.2.0}/docs/web/how-to/ci.md

@@ -4,7 +4,7 @@ SPDX-License-Identifier: Apache-2.0
 -->
 # Build the documentation in CI
 
-cpdocs runs from a fresh checkout: it configures every variant of every selected ref itself. The
+cpdocs runs from a fresh checkout: it builds every feature set of every selected ref itself. The
 checkout needs the history, tags and branches it documents, and the job needs Clang for C and C++
 units.
 
@@ -40,8 +40,9 @@ read from `CI_COMMIT_BRANCH`, `GITHUB_HEAD_REF` or `GITHUB_REF_NAME`, so the det
 CI job is documented as its working tree. `CPDOCS_CURRENT_BRANCH` overrides all three.
 
 A project may live in a subdirectory of its repository. Every ref is then checked out as a whole
-and the same subdirectory is documented; refs in which it does not exist are skipped. The examples
-in the cpdocs repository are published this way, with the branches and tags of cpdocs.
+and the same subdirectory is documented. Because `versions` is explicit, a configured ref that does not
+contain the project is an error rather than being silently skipped. The examples in the cpdocs repository
+use this same mechanism.
 
 A build system that runs cpdocs itself passes its own build directory:
 

cpdocs-0.2.0/docs/web/how-to/feature-sets.md

@@ -0,0 +1,44 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Document feature-dependent APIs
+
+The build system owns the finite feature space worth documenting. cpdocs asks for the concrete
+feature sets, builds each one independently, and records where each extracted definition exists.
+
+Features and API languages are different concepts. With BESA, for example, a project can define a
+host/GPU implementation choice and optional MPI independently:
+
+```cmake
+foreach(_feature IN ITEMS host gpu mpi)
+  besa_add_feature("${_feature}")
+endforeach()
+
+besa_add_variant(implementation ONE_OF host gpu)
+besa_add_variant(parallel ZERO_OR_ONE mpi)
+besa_keyso_create_feature_set(supported PRODUCT implementation parallel)
+besa_set_feature_set(supported)
+```
+
+The resulting feature sets can be `host`, `host + mpi`, `gpu`, and `gpu + mpi`. The units selected
+by those sets carry their own semantic language (`cpp`, `cuda`, and so on) in the manifest.
+
+The cpdocs configuration repeats none of this project logic:
+
+```yaml
+contract: 3
+build:
+  feature-sets: >
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DBESA_CPDOCS_FEATURE_SETS_OUTPUT="{{output-file}}"
+  build: >
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DBESA_CPDOCS_FEATURE_SET="{{feature-set}}"
+    -DBESA_CPDOCS_MANIFEST_OUTPUT="{{output-file}}"
+    && cmake --build "{{tmpdir}}" --target besa.cpdocs
+```
+
+If the same qualified function has a C++ definition and a CUDA definition, cpdocs renders two API
+entries and marks them **C++** and **CUDA**. If the CUDA definition is identical in both `gpu` and
+`gpu + mpi`, it is rendered once and both feature sets are listed in its availability section.

cpdocs-0.2.0/docs/web/how-to/generated-headers.md

@@ -0,0 +1,36 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Document generated headers
+
+Generated API files must exist before the build command returns. The project provider lists the
+generated directory in `manifest.json` with `generated: true`, and the configured build command runs
+the target that produces it before cpdocs starts extraction.
+
+For example:
+
+```yaml
+build:
+  build: >
+    cmake -S "{{source}}" -B "{{tmpdir}}" -G Ninja
+    -DCPDOCS_FEATURE_SET="{{feature-set}}"
+    -DCPDOCS_MANIFEST_OUTPUT="{{output-file}}"
+    && cmake --build "{{tmpdir}}" --target generate-api-header
+```
+
+The corresponding manifest can expose both checked-in and generated API roots:
+
+```json
+{
+  "id": "acme",
+  "language": "cpp",
+  "api": [
+    {"path": "/src/include"},
+    {"path": "/tmp/build/generated/include", "generated": true}
+  ]
+}
+```
+
+Generated files are rendered like other source files and marked as generated because they have no
+location in the repository. The complete example is `examples/generated-cpp`.

cpdocs-0.2.0/docs/web/how-to/other-build-systems.md

@@ -0,0 +1,69 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Integrate another build system
+
+A build system integrates with cpdocs by producing the two JSON files in the
+[build-system contract](../reference/contract.md). cpdocs does not require CMake.
+
+For example, a small project-specific adapter can be configured as:
+
+```yaml
+contract: 3
+build:
+  feature-sets: >
+    python tools/minibuild.py feature-sets "{{output-file}}"
+  build: >
+    python tools/minibuild.py build "{{feature-set}}" "{{output-file}}"
+```
+
+The first command writes every configuration worth documenting. The second receives one selected
+`feature-set.json`; it may configure, build, run generators, or inspect the build system in any way
+needed before writing `manifest.json`.
+
+Python projects can use cpdocs' bundled helper:
+
+```yaml
+contract: 3
+build:
+  feature-sets: >
+    "{{python}}" -m cpdocs manifest python feature-sets
+    --source "{{source}}" --output "{{output-file}}"
+  build: >
+    "{{python}}" -m cpdocs manifest python build
+    --source "{{source}}" --feature-set "{{feature-set}}" --output "{{output-file}}"
+    --package mypackage --package-source src/mypackage
+```
+
+Rust projects need no project-local adapter. The bundled Cargo provider implements the same two
+commands directly:
+
+```yaml
+contract: 3
+build:
+  feature-sets: >
+    cpdocs rust feature-sets
+    --source "{{source}}" --output "{{output-file}}"
+  build: >
+    cpdocs rust build
+    --source "{{source}}" --feature-set "{{feature-set}}" --output "{{output-file}}"
+```
+
+The build command uses Cargo's nightly rustdoc JSON output. Pin a nightly toolchain with
+`rust-toolchain.toml`, or pass `--toolchain nightly-YYYY-MM-DD` to both commands when a project
+needs an exact schema version.
+
+Without additional configuration, every Cargo feature is considered independent and becomes one
+cpdocs feature set. For example, `simd` and `mpi` produce `features: [simd]` and `features: [mpi]`,
+not their Cartesian product. If the real project supports coupled configurations, declare the exact
+sets explicitly:
+
+```toml
+[package.metadata.cpdocs]
+feature-sets = [
+  ["mpi"],
+  ["cuda"],
+  ["mpi", "cuda"],
+]
+```

cpdocs-0.2.0/docs/web/how-to/properdocs.md

@@ -0,0 +1,47 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Mount the API in a ProperDocs site
+
+The project website lives in `docs/web`; the plugin builds the versioned API and mounts it:
+
+```yaml
+docs_dir: docs/web
+
+plugins:
+  - search
+  - cpdocs:
+      mount: reference/api
+```
+
+The plugin options and their defaults are `config: docs/cpdocs.yml`, `output: build` and
+`mount: reference/api`. `properdocs serve` also documents the checked-out working tree in situ,
+even when that branch is not selected by `versions.branches.include`. That working-tree version is
+the default during the development server, so local and uncommitted API changes are immediately
+visible. The plugin also registers the project source directories with ProperDocs' live-reload
+server, so changing source files triggers a rebuild automatically. `properdocs build` keeps the
+configured version-selection and default-version policy unchanged.
+
+Pages refer to API entities with `@apidocs::demo::solve`; see
+[semantic links](../reference/links.md). With `checks.broken-references: fail`, a reference to an
+entity that does not exist fails the build.
+
+## Mount nested ProperDocs sites
+
+A root site can ask the cpdocs plugin to build nested ProperDocs projects directly into the same
+output tree:
+
+```yaml
+plugins:
+  - cpdocs:
+      mount: reference/python-api
+      subsites:
+        - examples/basic-cpp
+        - examples/python-basic
+```
+
+Each path is relative to the root `properdocs.yml` and must contain its own `properdocs.yml`. No
+separate pre-build command is needed. `properdocs build` writes the nested site at that same path
+under `site_dir`; `properdocs serve` does the same on every relevant live rebuild and gives the
+nested cpdocs plugin the current-working-tree semantics used by the parent development server.

{cpdocs-0.1.0 → cpdocs-0.2.0}/docs/web/index.md

@@ -4,17 +4,17 @@ SPDX-License-Identifier: Apache-2.0
 -->
 # cpdocs
 
-cpdocs generates semantic, versioned API documentation for C, C++, Python and Rust projects. It
-reads declarations the way the compiler or interpreter sees them, merges every documented variant
+cpdocs generates semantic, versioned API documentation for C, C++, CUDA, HIP, Fortran, Python and Rust projects. It
+reads declarations the way the compiler or interpreter sees them, merges every documented feature set
 of the API into one reference, and publishes one directory per Git branch or tag.
 
 cpdocs does not know how a project is built. It asks the project's build system, through a small
-[contract](reference/contract.md), which variants exist and how to read each of them. CMake support
+[contract](reference/contract.md), which feature sets exist and how to build each of them. CMake support
 ships with cpdocs; any other build system implements the same two JSON manifests.
 
 ```console
 cpdocs build          # document the working tree
-cpdocs versions       # document the configured branches and tags
+cpdocs versions       # document the configured versions
 properdocs build      # build the project website with the API mounted
 ```
 

cpdocs-0.2.0/docs/web/reference/cli.md

@@ -0,0 +1,30 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Command line
+
+```text
+cpdocs build [--config docs/cpdocs.yml] [--output build] [--label main]
+cpdocs versions [--config docs/cpdocs.yml] [--output build]
+cpdocs manifest python feature-sets ...
+cpdocs manifest python build ...
+cpdocs rust feature-sets --source <project> --output <feature-sets.json>
+cpdocs rust build --source <project> --feature-set <feature-set.json> --output <manifest.json>
+```
+
+`build` documents the working tree into `<output>/cpdocs/current`. It always documents every
+feature set returned by `build.feature-sets`.
+
+`versions` documents the exact ordered `versions:` list from `cpdocs.yml` into
+`<output>/cpdocs/versions`.
+
+`manifest python` is a small provider for plain Python projects.
+
+`rust` is the built-in Cargo provider. `rust feature-sets` reads Cargo metadata. By default every
+declared Cargo feature is treated as a disjoint feature set and documented once; projects that need
+specific combinations can list them in `[package.metadata.cpdocs]`. `rust build` runs Cargo rustdoc
+with nightly JSON output and writes a normal cpdocs manifest.
+
+Feature-set inputs, manifests, scratch/build directories and command logs are kept below
+`<output>/cpdocs/work/<version>/feature-sets/`.

cpdocs-0.2.0/docs/web/reference/cmake.md

@@ -0,0 +1,58 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# CMake integration
+
+cpdocs does not inject a CMake module and does not add CMake commands to a project. A CMake project
+or a build framework used by that project implements the same two-file
+[build-system contract](contract.md) as any other build system.
+
+A project-local provider can be as small as ordinary `CMakeLists.txt` code which writes
+`feature-sets.json` when `CPDOCS_FEATURE_SETS_OUTPUT` is set and writes `manifest.json` when
+`CPDOCS_FEATURE_SET` and `CPDOCS_MANIFEST_OUTPUT` are set. The checked-in C and C++ examples use
+this pattern directly, so a normal CMake configuration exercises exactly the same project logic as
+cpdocs.
+
+For example, a project with one feature set can expose discovery with:
+
+```cmake
+if(CPDOCS_FEATURE_SETS_OUTPUT)
+  file(WRITE "${CPDOCS_FEATURE_SETS_OUTPUT}" "{\n"
+    "  \"cpdocs-feature-sets\": 1,\n"
+    "  \"project\": {\"name\": \"${PROJECT_NAME}\", \"version\": \"${PROJECT_VERSION}\"},\n"
+    "  \"feature-sets\": [{\"features\": []}]\n"
+    "}\n")
+endif()
+```
+
+and configure cpdocs with ordinary CMake invocations:
+
+```yaml
+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}}"
+```
+
+A framework such as BESA can provide the contract natively. In that case the project does not need
+cpdocs-specific provider code at all:
+
+```yaml
+build:
+  feature-sets: >
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DBESA_CPDOCS_FEATURE_SETS_OUTPUT="{{output-file}}"
+  build: >
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DBESA_CPDOCS_FEATURE_SET="{{feature-set}}"
+    -DBESA_CPDOCS_MANIFEST_OUTPUT="{{output-file}}"
+    && cmake --build "{{tmpdir}}" --target besa.cpdocs
+```
+
+The important boundary is the JSON contract, not CMake itself. cpdocs remains independent of BESA
+and of any other build framework.

cpdocs-0.2.0/docs/web/reference/configuration.md

@@ -0,0 +1,49 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# 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.
+
+A minimal configuration is:
+
+```yaml
+contract: 3
+
+build:
+  feature-sets: >
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DBESA_CPDOCS_FEATURE_SETS_OUTPUT="{{output-file}}"
+  build: >
+    cmake -S "{{source}}" -B "{{tmpdir}}"
+    -DBESA_CPDOCS_FEATURE_SET="{{feature-set}}"
+    -DBESA_CPDOCS_MANIFEST_OUTPUT="{{output-file}}"
+    && cmake --build "{{tmpdir}}" --target besa.cpdocs
+
+versions: [main, v2.0.0, v1.0.0]
+```
+
+The two commands are the whole build-system interface. `build.feature-sets` runs once per source
+version. `build.build` runs once for every feature set returned by the first command.
+
+| Key | Default | Meaning |
+| --- | --- | --- |
+| `build.feature-sets` | required | command that writes `feature-sets.json` |
+| `build.build` | required | command that consumes one `feature-set.json` and writes one `manifest.json` |
+| `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 |
+| `api.hide.cpp-namespaces` | none | glob patterns of C++ namespaces omitted with their contents |
+| `api.hide.python-modules` | `private` | `private` hides modules beginning with `_`; `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.