Skip to content

Build the documentation in CI

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.

GitHub Actions

- uses: actions/checkout@v7
  with:
    fetch-depth: 0
    persist-credentials: false
- run: pip install 'cpdocs[properdocs]' mkdocs-materialx
- run: properdocs build
- uses: actions/upload-pages-artifact@v5
  with:
    path: build/site

GitLab CI

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. 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 versions --output "$BUILD_DIR"

What a documentation build trusts

Building documentation runs code. cpdocs runs the build.feature-sets and build.build commands from cpdocs.yml, which build the project, for every documented ref; the build scripts of an older tag run as they are in that tag; and the compiler flags a compile database supplies, plugins included, are passed to Clang. Treat cpdocs.yml, the build system and every documented ref as code the job executes:

  • do not build documentation for untrusted changes in a job that holds secrets or write permissions, and never under pull_request_target;
  • give the documentation job read-only repository permissions and no persisted Git credentials, and deploy from a separate job that does not build;
  • keep secrets out of the checkout: cpdocs publishes the source files units declare, limited to files Git tracks in the checkout and to symbolic links that stay inside the project.