Skip to main content

cpdocs

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, 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.

cpdocs build          # document the working tree into build/cpdocs/current
cpdocs versions       # document the configured versions
properdocs build      # project website with the versioned API mounted

Language configurations

The optional languages field in docs/cpdocs.yml is a Keyso configuration space. cpdocs expands it using pykeyso, then runs build.feature-sets once per concrete configuration and build.build once per feature set discovered for that configuration. Both command templates receive dotted placeholders from the resulting nested dictionaries, such as {{cxx.standard}}, {{c.standard}}, {{fortran.standard}}, {{python.version}}, or {{rust.edition}}. The build system decides how to apply each value; cpdocs does not translate them into compiler flags.

languages:
  _product:
    - cxx:
        _nested:
          standard: [17, 20, 23]
    - python:
        _nested:
          version: ["3.11", "3.12"]

build:
  feature-sets: >-
    cmake -S "{{source}}" -B "{{tmpdir}}"
    -DCMAKE_CXX_STANDARD="{{cxx.standard}}"
    -DPROJECT_FEATURE_SETS_OUTPUT="{{output-file}}"
  build: >-
    cmake -S "{{source}}" -B "{{tmpdir}}"
    -DCMAKE_CXX_STANDARD="{{cxx.standard}}"
    -DPROJECT_FEATURE_SET="{{feature-set}}"
    -DPROJECT_CPDOCS_OUTPUT="{{output-file}}"
    && cmake --build "{{tmpdir}}" --target project.cpdocs

Use _set for explicitly paired combinations rather than the _product Cartesian product:

languages:
  _set:
    - cxx: {standard: 17}
      python: {version: "3.11"}
    - cxx: {standard: 23}
      python: {version: "3.12"}

Each concrete configuration has its own work directory. The merged API records both the language configuration and feature set in symbol availability, including overload signatures. If languages is omitted, cpdocs performs the original single build configuration, and the existing {{source}}, {{tmpdir}}, {{output-file}}, {{feature-set}}, and {{python}} placeholders continue to work unchanged.

Language-version availability

cpdocs determines availability from the public declarations extracted for each concrete language configuration and discovered feature set. It does not inspect or require any cpdocs-specific annotations. C/C++ projects can use their usual #if __cplusplus or __STDC_VERSION__ guards; Clang analyzes the resulting declarations using the standard and flags supplied by the project's manifest. Rust and Fortran availability likewise follows the API that the configured provider extracts.

For Python, the static extractor recognizes native sys.version_info comparisons (including sys.version_info[:2], .major/.minor, imported aliases, elif/else, and simple boolean combinations) for a configured python.version. It selects those branches without importing or executing project code. Guards it cannot evaluate are not interpreted as unconditional availability; API definitions nested in such guards are omitted as before. Projects with complex dynamic exports should provide a version-specific manifest/provider rather than rely on this limited static analysis. Python source parsing uses the host cpdocs interpreter, so syntax introduced after that interpreter's release may require running cpdocs with a newer interpreter; this is not equivalent to testing the package on each target interpreter.

The generated API displays language versions/standards separately from feature sets for each function and overload, with links to the exact combinations of the two. Only configurations actually analyzed are shown: C++20 and C++23 do not imply C++20+, and API presence does not assert that functionality was tested.

See examples/cpp-standards for a runnable CMake example building C++17, C++20, and C++23 from one Keyso configuration. It includes functions added and removed between standards and standard-dependent overloads, with an end-to-end test for their generated availability documentation.

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.

API renderer resources

The standalone API renderer keeps its nontrivial static content under the repository-level share/cpdocs/api/: HTML page and redirect templates (layout.html, redirect.html, versions-redirect.html), the default index.md introduction, reusable page fragments, cpdocs-api.css, and cpdocs-api.js plus the early-loading cpdocs-api-init.js. Python loads these using the shared cpdocs.resources.shared_text and shared_template helpers (based on importlib.resources), without relying on a source checkout. The wheel configuration force-includes share/ at the wheel root ("share" = "share"), so unrelated programs can also read the files through the shared share namespace. The cpdocs/ prefix avoids collisions with resources owned by other programs.

Browser assets are copied into the published site's assets/ directory with content-derived cache keys. Small dynamically assembled HTML fragments and Python docstrings remain in code; static, substantive prose, templates, stylesheets, and scripts should be file-backed rather than embedded as multiline Python string literals. Test-only example source and fake-provider scripts live separately in test/share/ so they are not installed with the runtime package.

Development

uv sync
uv run pytest
uv run ruff check && uv run ruff format --check

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.

Metadata

Release files for cpdocs 0.5.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for cpdocs 0.5.1
File Size Uploaded Provenance Actions
cpdocs-0.5.1.tar.gz 188.6 kB Without provenance Details for cpdocs-0.5.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for cpdocs 0.5.1
File Interpreter ABI Platform Actions
cpdocs-0.5.1-py3-none-any.whl Python 3 none any Details for cpdocs-0.5.1-py3-none-any.whl

Total release size: 294.2 kB

Release files / cpdocs-0.5.1.tar.gz

Download URL cpdocs-0.5.1.tar.gz
Size 188.6 kB
Tags Source
SHA-256 checksum
How to use checksums
b093bb9bba9168ba1f3355947ac9db4548fef091d83bde1ad257203fd06f45d9
BLAKE2b-256 checksum
How to use checksums
814718dd98a2a13dcc9aface7dfa1e0fbced7c944b848f9d7b23e9b806cf69ea
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via Hatch/1.18.1 {"ci":null,"cpu":"x86_64","distro":{"libc":{"lib":"glibc","version":"2.44"},"name":"Arch Linux"},"implementation":{"name":"CPython","version":"3.14.8"},"installer":{"name":"hatch","version":"1.18.1"},"openssl_version":"OpenSSL 3.6.5 29 Sep 2026","python":"3.14.8","system":{"name":"Linux","release":"6.18.57-2-lts"}} HTTPX2/2.13.1

Release files / cpdocs-0.5.1-py3-none-any.whl

Download URL cpdocs-0.5.1-py3-none-any.whl
Size 105.6 kB
Tags Python 3
SHA-256 checksum
How to use checksums
3a77d08f936c83ff16b36ff47dda5e725141bbe510acf2e01373ff6b28b31634
BLAKE2b-256 checksum
How to use checksums
4362d81a41dfa1837e9e96c4ce8e47c5a5845b822f0dc09c3de76bda4b0aab2f
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
No
Uploaded via Hatch/1.18.1 {"ci":null,"cpu":"x86_64","distro":{"libc":{"lib":"glibc","version":"2.44"},"name":"Arch Linux"},"implementation":{"name":"CPython","version":"3.14.8"},"installer":{"name":"hatch","version":"1.18.1"},"openssl_version":"OpenSSL 3.6.5 29 Sep 2026","python":"3.14.8","system":{"name":"Linux","release":"6.18.57-2-lts"}} HTTPX2/2.13.1

Security for cpdocs 0.5.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

No provenance found

None of the files in this release were uploaded with provenance metadata.

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page