ci: add docs.rs compatibility checks

.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

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 <manifest-path> [<manifest-path> ...]
+```
+
 #### `coverage-apps.sh`
 **Generate test coverage reports**
 - Uses cargo-tarpaulin for coverage analysis

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 <manifest-path> [<manifest-path> ...]" >&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

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"]