lychee.yml

# SPDX-FileCopyrightText: Copyright (c) 2026 NVIDIA CORPORATION & AFFILIATES. All rights reserved.
#
# SPDX-License-Identifier: Apache-2.0

# Build documentation nightly and warm the link cache, reporting unresolved links
# as warnings. Full PR CI reuses successful checks in build-docs.yml.
# Ordinary PR updates run pre-commit without Lychee and do not build docs here.

name: "CI: Documentation links"

on:
  workflow_call:
    inputs:
      concurrency-suffix:
        description: "Keep a caller's test mode separate from its full run"
        type: string
        default: full
      refresh-cache:
        description: "Check links afresh and publish a new cache baseline"
        type: boolean
        default: false
  workflow_dispatch:
    inputs:
      refresh-cache:
        description: "Check links afresh and publish a new cache baseline"
        type: boolean
        default: false

permissions:
  contents: read

concurrency:
  group: ${{ github.workflow }}-${{ github.ref }}-${{ github.event_name }}-${{ inputs.refresh-cache || false }}-${{ inputs.concurrency-suffix || 'full' }}
  cancel-in-progress: true

defaults:
  run:
    shell: bash --noprofile --norc -euo pipefail {0}

env:
  # Build with the committed docs environment without resolving other environments.
  PIXI_FROZEN: "true"

jobs:
  links:
    name: Lychee (${{ matrix.kind }})
    runs-on: ubuntu-latest
    timeout-minutes: 60
    strategy:
      fail-fast: false
      matrix:
        kind: [authored, rendered]
    steps:
      - name: Checkout checked revision
        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
        with:
          fetch-depth: 0
          # Keep SCM history/tags without downloading historical source blobs.
          filter: blob:none
          persist-credentials: false
          # Rendered docs build cuda.core against the pinned CCCL headers.
          submodules: ${{ matrix.kind == 'rendered' }}

      - name: Set up Python
        uses: actions/setup-python@5fda3b95a4ea91299a34e894583c3862153e4b97 # v7.0.0
        with:
          python-version: "3.14"

      - name: Setup pixi
        if: ${{ matrix.kind == 'rendered' }}
        uses: ./.github/actions/setup-pixi

      - name: Build all documentation from sources
        if: ${{ matrix.kind == 'rendered' }}
        run: pixi run --manifest-path cuda_core/pixi.toml -e docs docs-build-all-latest

      - name: Check documentation links
        uses: ./.github/actions/check-doc-links
        with:
          kind: ${{ matrix.kind }}
          refresh-cache: ${{ inputs.refresh-cache || false }}
          failure-policy: ${{ inputs.refresh-cache && 'cache-warm' || 'check' }}