cpdocs 0.1.0__tar.gz

cpdocs-0.1.0/.github/workflows/docs.yml

@@ -0,0 +1,72 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+name: documentation
+
+# The published site is always built from the default branch: with the full history, cpdocs
+# documents every configured branch and tag from there. The github-pages environment only accepts
+# deployments from the default branch, so a pushed tag does not deploy itself; it starts this
+# workflow on the default branch, whose build then includes the new tag.
+
+on:
+  push:
+    branches: [main]
+    tags: ["*"]
+  pull_request:
+  workflow_dispatch:
+
+permissions:
+  contents: read
+
+jobs:
+  rebuild-for-tag:
+    if: github.ref_type == 'tag'
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write
+    steps:
+      - name: Rebuild the site on the default branch
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: >
+          gh workflow run docs.yml
+          --repo "${{ github.repository }}"
+          --ref "${{ github.event.repository.default_branch }}"
+
+  build:
+    if: github.ref_type != 'tag'
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+      - 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: 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
+
+  deploy:
+    if: >
+      github.event_name != 'pull_request'
+      && github.ref == format('refs/heads/{0}', github.event.repository.default_branch)
+    needs: build
+    runs-on: ubuntu-latest
+    permissions:
+      pages: write
+      id-token: write
+    concurrency:
+      group: github-pages
+      cancel-in-progress: false
+    environment:
+      name: github-pages
+      url: ${{ steps.deployment.outputs.page_url }}
+    steps:
+      - name: Deploy
+        id: deployment
+        uses: actions/deploy-pages@v4

cpdocs-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,20 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+name: test
+
+on:
+  push:
+  pull_request:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - 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: Lint
+        run: uv run ruff check && uv run ruff format --check
+      - name: Test
+        run: uv run pytest -q

cpdocs-0.1.0/.gitignore

@@ -0,0 +1,9 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+__pycache__/
+.pytest_cache/
+.ruff_cache/
+.venv/
+build/
+dist/
+*.egg-info/

cpdocs-0.1.0/LICENSES/Apache-2.0.txt

@@ -0,0 +1,202 @@
+
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.

cpdocs-0.1.0/PKG-INFO

@@ -0,0 +1,48 @@
+Metadata-Version: 2.5
+Name: cpdocs
+Version: 0.1.0
+Summary: Semantic, versioned API documentation for C, C++, 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
+Requires-Dist: properdocs>=1.6.7; extra == 'properdocs'
+Description-Content-Type: text/markdown
+
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# cpdocs
+
+cpdocs generates semantic, versioned API documentation for C, C++, 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.
+
+```console
+cpdocs build          # document the working tree into build/cpdocs/current
+cpdocs versions       # document the configured branches and tags
+properdocs build      # project website with the versioned API mounted
+```
+
+The configuration lives in `docs/cpdocs.yml`, the API introduction in `docs/api/index.md` and the
+ProperDocs pages in `docs/web`. The documentation starts at `docs/web/index.md`; the `examples/`
+directory holds standalone projects that the test suite builds.
+
+## Development
+
+```console
+uv sync
+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.

cpdocs-0.1.0/REUSE.toml

@@ -0,0 +1,8 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+version = 1
+
+[[annotations]]
+path = "uv.lock"
+SPDX-FileCopyrightText = "2026 cpdocs developers"
+SPDX-License-Identifier = "Apache-2.0"

cpdocs-0.1.0/docs/api/index.md

@@ -0,0 +1,8 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# {{ project }} Python API
+
+The Python API of cpdocs {{ version }}. The command line is documented in the
+[project documentation](projectdocs:reference/cli/).

cpdocs-0.1.0/docs/cpdocs.yml

@@ -0,0 +1,19 @@
+# SPDX-FileCopyrightText: 2026 cpdocs developers
+# SPDX-License-Identifier: Apache-2.0
+contract: 1
+
+build:
+  describe:
+    - ["{python}", -m, cpdocs, manifest, python, --request, "{request}",
+       --package, cpdocs, --source, src/cpdocs]
+
+versions:
+  branches:
+    include: [main]
+  tags:
+    select: all
+  default: main
+  legacy: skip
+
+site:
+  copyright: Copyright © cpdocs developers · Apache-2.0

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

@@ -0,0 +1,25 @@
+<!--
+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 published documentation includes each
+example's site, versioned with the branches and tags of the cpdocs repository.
+
+| 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` | besa-style features and three variants; 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/) |
+| `python-basic` | a plain Python package, answered by `cpdocs manifest python` | [python-basic](python-basic/) |
+
+To build the example sites locally after `properdocs build`:
+
+```console
+uv run python tools/build_example_sites.py
+```

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

@@ -0,0 +1,20 @@
+<!--
+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 describes the project and configures each variant. cpdocs only
+   reads the manifests.
+2. **Extraction.** Each unit of each variant becomes an API graph: Clang for C and C++, `ast` for
+   Python, rustdoc JSON for Rust.
+3. **Merge.** The graphs of all units of a variant are combined; the variant graphs are then merged
+   so that every entity records the variants it exists in.
+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.1.0/docs/web/explanation/variants.md

@@ -0,0 +1,17 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Why the build system owns variants
+
+An API that depends on build features exists in several forms. The reliable way to see each form
+is to configure the project the way a user would and read what the compiler then sees.
+
+Only the build system knows how a feature becomes a definition, an include directory or a generated
+header, and that knowledge changes from release to release. cpdocs therefore asks each ref's own
+build system for its variants and their commands instead of keeping a copy of that knowledge in its
+configuration. An old tag is documented with the features it had, and a change of build system
+does not change `cpdocs.yml`.
+
+What remains in `cpdocs.yml` is publishing policy: which refs to build, how many variants each
+gets, and what the site looks like.

cpdocs-0.1.0/docs/web/how-to/ci.md

@@ -0,0 +1,50 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+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
+checkout needs the history, tags and branches it documents, and the job needs Clang for C and C++
+units.
+
+## GitHub Actions
+
+```yaml
+- uses: actions/checkout@v4
+  with:
+    fetch-depth: 0
+- run: pip install 'cpdocs[properdocs]' mkdocs-materialx
+- run: properdocs build
+- uses: actions/upload-pages-artifact@v3
+  with:
+    path: build/site
+```
+
+## GitLab CI
+
+```yaml
+docs:
+  variables:
+    GIT_DEPTH: 0
+  script:
+    - git fetch --tags origin '+refs/heads/*:refs/remotes/origin/*'
+    - pip install 'cpdocs[properdocs]' mkdocs-materialx
+    - properdocs build
+  artifacts:
+    paths: [build/site]
+```
+
+Branch names are matched against local and remote-tracking branches. The branch being built is
+read from `CI_COMMIT_BRANCH`, `GITHUB_HEAD_REF` or `GITHUB_REF_NAME`, so the detached checkout of a
+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.
+
+A build system that runs cpdocs itself passes its own build directory:
+
+```console
+cpdocs versions --output "$BUILD_DIR"
+```

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

@@ -0,0 +1,19 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Document generated headers
+
+Headers produced during the build are listed as `GENERATED` API roots, and the targets that
+produce them as `DEPENDS`:
+
+```cmake
+cpdocs_api(UNIT acme LANGUAGE cpp TARGET acme_generated
+  API include GENERATED ${GENERATED_INCLUDE} DEPENDS generate-api-header)
+```
+
+The adapter's `cpdocs-prepare` target builds the `DEPENDS` targets before it writes the variant
+manifest, so the headers exist when Clang reads them. Generated files are rendered like any other
+source file and marked as generated, since they have no location in the repository.
+
+The complete example is `examples/generated-cpp`.

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

@@ -0,0 +1,40 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Use a build system other than CMake
+
+cpdocs talks to a build system only through the [contract](../reference/contract.md). A build
+system supports cpdocs by answering two requests:
+
+1. **describe**: write the project name, feature axes, units and variants, with the commands that
+   configure each variant;
+2. **variant**: write, per unit, the API roots and the options needed to parse them.
+
+`examples/cpp-features/tools/minibuild.py` is a complete implementation in about seventy lines of
+Python. Its configuration names it as the describe command:
+
+```yaml
+contract: 1
+build:
+  describe:
+    - ["{python}", tools/minibuild.py, "{request}"]
+```
+
+The test suite checks that it produces the same API reference as the CMake build of the same
+project.
+
+## Plain Python packages
+
+A package built with a standard backend such as hatchling needs no configuration step. cpdocs' own
+helper answers the requests for it:
+
+```yaml
+contract: 1
+build:
+  describe:
+    - ["{python}", -m, cpdocs, manifest, python, --request, "{request}",
+       --package, dice, --source, src/dice]
+```
+
+It reads the project name and version from `pyproject.toml` and documents one `default` variant.

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

@@ -0,0 +1,23 @@
+<!--
+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` rebuilds the API when a file tracked by Git changes.
+
+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.

cpdocs-0.1.0/docs/web/how-to/variants.md

@@ -0,0 +1,53 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+SPDX-License-Identifier: Apache-2.0
+-->
+# Document feature variants
+
+A project whose API depends on build features declares the features and the variants to document
+in its build system. cpdocs builds every declared variant and records, per entity, the variants in
+which it exists. This guide uses CMake and the besa feature convention.
+
+## Declare the feature axis
+
+```cmake
+include(cmake/feature.cmake)
+set(PROJECT_FEATURES "none" CACHE STRING "Optional features: none, mpi, cuda, or all")
+besa_feature(PROJECT_FEATURES VALUES "mpi;cuda" DESCRIPTION "Optional solver features")
+
+if(PROJECT_FEATURES_MPI)
+  target_compile_definitions(demo INTERFACE DEMO_HAVE_MPI=1)
+endif()
+```
+
+The mapping from a feature to a compile definition stays in the build system; cpdocs never sees it.
+
+## Declare the variants
+
+```cmake
+if(COMMAND cpdocs_api)
+  cpdocs_features(PROJECT_FEATURES)
+  cpdocs_variant(serial PRIMARY PROJECT_FEATURES none)
+  cpdocs_variant(mpi PROJECT_FEATURES mpi)
+  cpdocs_variant(full PROJECT_FEATURES all)
+  cpdocs_api(UNIT demo LANGUAGE cpp TARGET demo API include)
+endif()
+```
+
+`cpdocs_features` takes the valid values from `PROJECT_FEATURES_ARRAY`, which `besa_feature`
+sets. The primary variant is the one built when only one variant is wanted.
+
+## Build fewer variants for branches
+
+Which refs build all variants is publishing policy, set in `docs/cpdocs.yml`:
+
+```yaml
+versions:
+  branches:
+    include: [main]
+    variants: primary
+  tags:
+    variants: all
+```
+
+The complete example is `examples/cpp-features`.

cpdocs-0.1.0/docs/web/index.md

@@ -0,0 +1,21 @@
+<!--
+SPDX-FileCopyrightText: 2026 cpdocs developers
+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
+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
+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
+properdocs build      # build the project website with the API mounted
+```
+
+Start with the [tutorial](tutorials/first-reference.md).