Developer documentation builds

epi4you now links Rust compilation and documentation production.

Build behavior

When you run:

cargo build

the package build script will also try to build the Sphinx documentation.

The build order is:

  1. try local sphinx-build,

  2. if Sphinx is not installed locally, try a container runtime, and

  3. use the dedicated AlmaLinux 9 image described by docs/Dockerfile.docs.

Why use a container

The docs toolchain is not part of the Rust crate itself. Using a dedicated docs container keeps the host machine light while still making documentation production reproducible and easy to trigger from the normal Cargo workflow.

The image is intentionally narrow in scope:

  • base image: AlmaLinux 9,

  • Python available,

  • Sphinx installed from docs/requirements.txt, and

  • default command aimed at make -C docs html.

Skipping docs intentionally

If you need a fast Rust-only build or you are in an environment where neither Sphinx nor a usable container runtime is available, you can skip docs with:

EPI4YOU_SKIP_DOCS=1 cargo build

Relevant files

  • build.rs

  • docs/Dockerfile.docs

  • docs/Makefile

  • docs/requirements.txt

  • .github/workflows/pages.yml

Publishing to GitHub Pages

The repository includes a GitHub Actions workflow that:

  • installs Python and Sphinx,

  • runs cargo build,

  • collects docs/build/html, and

  • deploys that artifact to GitHub Pages.

The workflow asks actions/configure-pages to enable Pages automatically on first deployment. That avoids the common failure where the repository does not yet have a Pages site configured.

You may still need to enable Pages in the repository settings so GitHub treats GitHub Actions as the publication source for the site, especially if the repository belongs to an organisation with restricted Pages or Actions policies.