check-doc-links.yml

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

name: "CI: Check rendered docs links"

on:
  workflow_call:
    inputs:
      docs-artifact:
        description: "Artifact containing the rendered docs HTML tree"
        required: false
        default: docs-rendered-html
        type: string

jobs:
  check:
    name: Check rendered docs links
    if: ${{ github.repository_owner == 'nvidia' && startsWith(github.ref_name, 'pull-request/') }}
    runs-on: ubuntu-latest
    permissions:
      actions: read
      contents: read
      pull-requests: read
    defaults:
      run:
        shell: bash -el {0}
    steps:
      - name: Extract PR number
        run: |
          PR_NUMBER="${GITHUB_REF_NAME#pull-request/}"
          if [[ ! "${PR_NUMBER}" =~ ^[0-9]+$ ]]; then
            echo "error: cannot extract PR number from ref ${GITHUB_REF_NAME}" >&2
            exit 1
          fi
          echo "PR_NUMBER=${PR_NUMBER}" >> "${GITHUB_ENV}"

      - name: Download rendered docs
        uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c  # v8.0.1
        with:
          name: ${{ inputs.docs-artifact }}
          path: rendered-docs

      - name: Write rendered docs file list
        run: |
          find "${GITHUB_WORKSPACE}/rendered-docs" -type f -name '*.html' ! -path '*/_static/*' \
            | LC_ALL=C sort > lychee-rendered-html-files.txt
          if [[ ! -s lychee-rendered-html-files.txt ]]; then
            echo "error: no rendered HTML pages found for lychee" >&2
            exit 1
          fi
          wc -l lychee-rendered-html-files.txt

      - name: Restore lychee cache
        id: restore-lychee-cache
        uses: actions/cache/restore@0057852bfaa89a56745cba8c7296529d2fc39830  # v4
        with:
          path: .lycheecache
          key: docs-rendered-lychee-${{ env.PR_NUMBER }}-${{ github.sha }}
          restore-keys: |
            docs-rendered-lychee-${{ env.PR_NUMBER }}-

      - name: Check rendered docs links
        uses: lycheeverse/lychee-action@6da1d14f3a43098a294b7696d93d938aa8d20fc0  # unreleased: supports v0.24.x archive layout
        with:
          # PR-preview canonical URLs are checked by the preview deployment workflow.
          # The cuda-bindings #id links are docutils "problematic" anchors from generated API docs.
          # TODO: Remove this exclusion after cybind stops emitting those problematic anchors.
          # Preferred Networks rejects hosted-runner GETs, but the URL is browser reachable.
          args: >-
            --files-from ${{ github.workspace }}/lychee-rendered-html-files.txt
            --include-fragments=full
            --cache
            --max-cache-age 1d
            --max-concurrency 16
            --host-concurrency 2
            --host-request-interval 250ms
            --max-retries 3
            --retry-wait-time 5
            --timeout 30
            --no-progress
            --exclude '^https://nvidia\.github\.io/cuda-python/pr-preview/pr-[0-9]+/'
            --exclude '^file://.*/cuda-bindings/latest/module/(driver|runtime)\.html#id[0-9]+$'
            --exclude '^https://www\.preferred\.jp/en/?$'
          fail: true
          failIfEmpty: true
          format: markdown
          jobSummary: false
          lycheeVersion: v0.24.2
          output: lychee-rendered-html.md
          token: ${{ github.token }}

      - name: Save lychee cache
        if: ${{ always() && steps.restore-lychee-cache.outputs.cache-hit != 'true' && steps.restore-lychee-cache.outputs.cache-primary-key != '' }}
        uses: actions/cache/save@0057852bfaa89a56745cba8c7296529d2fc39830  # v4
        with:
          path: .lycheecache
          key: ${{ steps.restore-lychee-cache.outputs.cache-primary-key }}