docs.yml

name: Documentation

on:
  workflow_dispatch: {}
  workflow_call:
    inputs:
      ref:
        type: string
        required: false
        default: ""
  push:
    branches: [main]
  pull_request:
    branches: [main]

# Auto-cancel superseded PR runs: pushing again to a feature branch
# supersedes the in-flight run instead of queueing behind it. Non-PR
# events key on run_id so each gets its own group -- a shared group keeps
# only ONE pending run, which would silently drop queued main SHAs.
concurrency:
  group: docs.yml-${{ inputs.ref != '' && github.run_id || (github.event_name == 'pull_request' && github.ref || github.run_id) }}
  cancel-in-progress: ${{ github.event_name == 'pull_request' }}

env:
  FORCE_JAVASCRIPT_ACTIONS_TO_NODE24: "true"

jobs:
  docs:
    name: Documentation
    runs-on: ubuntu-latest
    timeout-minutes: 15
    env:
      RUSTDOCFLAGS: "-D warnings"
    steps:
      - uses: actions/checkout@v6
        with:
          ref: ${{ inputs.ref }}
      - name: Setup soldr
        id: setup-soldr
        uses: zackees/setup-soldr@v0
        with:
          cache: true
          build-cache: true
          target-cache: true
          prebuild-deps: none
          # Opt out of the implicit `SOLDR_LINKER=fast` injection so cargo /
          # rust-toolchain.toml stays in charge. Silences the routine
          # "defaulting SOLDR_LINKER=fast" warning (issue #400 /
          # setup-soldr#377).
          linker: platform-default
          # Realistic zccache payload for the doc build can exceed the
          # 512 MiB action default (issue #400). Raise the soft warn
          # threshold; hard cap stays at the action default (6 GiB).
          cache-payload-warn-bytes: 2GiB

      - name: Build docs
        run: soldr cargo doc --workspace --no-deps