diff --git a/.github/workflows/docs-rs.yaml b/.github/workflows/docs-rs.yaml new file mode 100644 index 000000000..83cb93dc7 --- /dev/null +++ b/.github/workflows/docs-rs.yaml @@ -0,0 +1,33 @@ +name: Docs.rs + +on: + pull_request: + branches: + - main + push: + branches: + - main + +env: + CARGO_TERM_COLOR: always + +jobs: + docs-rs: + runs-on: ubuntu-latest + steps: + - name: Checkout repository + uses: actions/checkout@v7 + + - name: Build docs.rs sandbox + run: docker build --file scripts/docs-rs.Dockerfile --tag sv2-docs-rs . + + - name: Check docs.rs compatibility + run: | + docker run --rm --network none sv2-docs-rs \ + stratum-apps/Cargo.toml \ + pool-apps/pool/Cargo.toml \ + pool-apps/jd-server/Cargo.toml \ + miner-apps/jd-client/Cargo.toml \ + miner-apps/translator/Cargo.toml \ + integration-tests/Cargo.toml \ + bitcoin-core-sv2/Cargo.toml diff --git a/scripts/README.md b/scripts/README.md index f1b363414..a95d1df62 100644 --- a/scripts/README.md +++ b/scripts/README.md @@ -51,6 +51,17 @@ This directory contains utility scripts for building, testing, and publishing th ### 📊 Testing & Coverage Scripts +#### `docs-rs-check.sh` +**Run docs.rs-like builds for one or more crates** +- Uses dependencies prefetched by the CI sandbox image +- Runs `cargo docs-rs --offline` while the container has no network +- Intended for CI jobs that validate docs.rs compatibility + +**Usage:** +```bash +./scripts/docs-rs-check.sh [ ...] +``` + #### `coverage-apps.sh` **Generate test coverage reports** - Uses cargo-tarpaulin for coverage analysis diff --git a/scripts/docs-rs-check.sh b/scripts/docs-rs-check.sh new file mode 100755 index 000000000..b2b834344 --- /dev/null +++ b/scripts/docs-rs-check.sh @@ -0,0 +1,21 @@ +#!/usr/bin/env bash + +# Run docs.rs-like documentation builds for one or more crates. +# Arguments: +# paths to Cargo.toml files +set -euo pipefail + +if [ "$#" -eq 0 ]; then + echo "Usage: $0 [ ...]" >&2 + exit 2 +fi + +for manifest_path in "$@"; do + if [ ! -f "$manifest_path" ]; then + echo "Manifest not found: $manifest_path" >&2 + exit 1 + fi + + echo "Building docs for ${manifest_path}" + cargo +nightly docs-rs --manifest-path="$manifest_path" --offline +done diff --git a/scripts/docs-rs.Dockerfile b/scripts/docs-rs.Dockerfile new file mode 100644 index 000000000..2d3eb08de --- /dev/null +++ b/scripts/docs-rs.Dockerfile @@ -0,0 +1,33 @@ +FROM rustlang/rust:nightly-bookworm + +RUN apt-get update \ + && apt-get install --yes --no-install-recommends \ + capnproto \ + clang \ + cmake \ + libcapnp-dev \ + libssl-dev \ + pkg-config \ + && rm -rf /var/lib/apt/lists/* + +RUN cargo install cargo-docs-rs --locked + +RUN useradd --create-home --uid 1000 docs \ + && chown --recursive docs:docs /usr/local/cargo + +WORKDIR /workspace +COPY --chown=docs:docs . . + +USER docs + +# Populate Cargo's cache while image builds still have network access. The +# resulting image runs the documentation build with Docker networking disabled. +RUN cargo fetch --manifest-path=stratum-apps/Cargo.toml \ + && cargo fetch --manifest-path=pool-apps/pool/Cargo.toml \ + && cargo fetch --manifest-path=pool-apps/jd-server/Cargo.toml \ + && cargo fetch --manifest-path=miner-apps/jd-client/Cargo.toml \ + && cargo fetch --manifest-path=miner-apps/translator/Cargo.toml \ + && cargo fetch --manifest-path=integration-tests/Cargo.toml \ + && cargo fetch --manifest-path=bitcoin-core-sv2/Cargo.toml + +ENTRYPOINT ["./scripts/docs-rs-check.sh"]