build-docs.yml

name: Deploy CCCL Documentation

on:
  # Runs on pushes targeting the default branch
  push:
    branches: ["main"]

  # Allows you to run this workflow manually from the Actions tab
  workflow_dispatch:

  # Reusable workflow for PR previews
  workflow_call:
    inputs:
      destination_dir:
        description: "Destination directory for deployment"
        required: false
        default: "docs"
        type: string
      pr_number:
        description: "PR number for preview URL generation"
        required: false
        default: ""
        type: string
      remove_pr_preview:
        description: "If true, deploy empty folder to remove PR preview"
        required: false
        default: false
        type: boolean
    outputs:
      preview_url:
        description: "The URL where the PR preview is deployed"
        value: ${{ jobs.build-and-deploy.outputs.preview_url }}

# Sets permissions of the GITHUB_TOKEN to allow GitHub Pages deployment and PR comments
permissions:
  contents: write
  pull-requests: write
  pages: write

# Serialize deploy/cleanup for same PR to prevent races
concurrency:
  group: ${{ inputs.pr_number && format('pr-preview-{0}', inputs.pr_number) || 'pages-main' }}
  cancel-in-progress: false

jobs:
  # Build and deploy job
  build-and-deploy:
    runs-on: ${{ github.repository == 'NVIDIA/cccl' && 'linux-amd64-cpu32' || 'ubuntu-latest' }}
    outputs:
      preview_url: ${{ steps.set-preview-url.outputs.preview_url }}
    steps:
      - name: Validate inputs
        run: |
          if [ "${{ inputs.remove_pr_preview }}" = "true" ] && [ -z "${{ inputs.pr_number }}" ]; then
            echo "Error: remove_pr_preview requires pr_number to be set"
            exit 1
          fi
          if [ -n "${{ inputs.pr_number }}" ] && ! echo "${{ inputs.pr_number }}" | grep -qE '^[0-9]+$'; then
            echo "Error: pr_number must be numeric (got: '${{ inputs.pr_number }}')"
            exit 1
          fi

      - name: Set preview URL
        id: set-preview-url
        run: |
          if [ -n "${{ inputs.pr_number }}" ]; then
            echo "preview_url=https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/pr-preview/pr-${{ inputs.pr_number }}/" >> $GITHUB_OUTPUT
          else
            echo "preview_url=" >> $GITHUB_OUTPUT
          fi

      - name: Checkout
        uses: actions/checkout@v6
        with:
          persist-credentials: false

      - name: Build docs
        if: ${{ !inputs.remove_pr_preview }}
        uses: ./.github/actions/docs-build
        with:
          upload_workflow_artifact: "true"

      - name: Create empty directory for cleanup
        if: ${{ inputs.remove_pr_preview }}
        run: |
          mkdir -p _site
          echo "# Preview Removed" > _site/README.md
          echo "This PR preview has been removed because the pull request was closed." >> _site/README.md

      - name: Set commit message
        id: commit-msg
        run: |
          if [ "${{ inputs.remove_pr_preview }}" = "true" ]; then
            echo "message=Clean up doc preview for PR ${{ inputs.pr_number }} (${{ github.sha }})" >> $GITHUB_OUTPUT
          elif [ -n "${{ inputs.pr_number }}" ]; then
            echo "message=Deploy doc preview for PR ${{ inputs.pr_number }} (${{ github.sha }})" >> $GITHUB_OUTPUT
          else
            echo "message=Deploy main docs (${{ github.sha }})" >> $GITHUB_OUTPUT
          fi

      - name: Deploy .nojekyll to docs root
        if: ${{ github.event_name == 'push' && !inputs.pr_number }} # Only create .nojekyll for main docs deployment
        run: |
          mkdir -p _nojekyll
          touch _nojekyll/.nojekyll

      - name: Ensure Jekyll is disabled for GitHub Pages
        if: ${{ github.event_name == 'push' && !inputs.pr_number }} # Only deploy .nojekyll for main docs, not PR previews
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_nojekyll
          publish_branch: gh-pages
          destination_dir: docs
          keep_files: true
          commit_message: "Deploy .nojekyll to disable Jekyll processing"

      - name: Deploy to GitHub Pages
        if: ${{ github.event_name == 'push' && !inputs.pr_number }} # Don't deploy doc previews for now to avoid overflowing gh-pages branch
        uses: peaceiris/actions-gh-pages@v3
        with:
          github_token: ${{ secrets.GITHUB_TOKEN }}
          publish_dir: ./_site
          publish_branch: gh-pages
          destination_dir: ${{ inputs.destination_dir || 'docs' }}
          keep_files: true
          commit_message: ${{ steps.commit-msg.outputs.message }}

#      - name: Leave PR preview comment
#        if: ${{ inputs.pr_number && !inputs.remove_pr_preview }}
#        uses: marocchino/sticky-pull-request-comment@67d0dec7b07ed060a405f9b2a64b8ab319fdd7db  # v2.9.2
#        with:
#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#          header: pr-preview
#          number: ${{ inputs.pr_number }}
#          skip_unchanged: true
#          message: |
#            ## 📖 Doc Preview CI
#
#            🚀 **Preview URL:** [${{ steps.set-preview-url.outputs.preview_url }}](${{ steps.set-preview-url.outputs.preview_url }})
#
#           _Preview will be available once GitHub Pages deployment completes._

#      - name: Leave cleanup comment
#        if: ${{ inputs.pr_number && inputs.remove_pr_preview }}
#        uses: marocchino/sticky-pull-request-comment@67d0dec7b07ed060a405f9b2a64b8ab319fdd7db  # v2.9.2
#        with:
#          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
#          header: pr-preview
#          number: ${{ inputs.pr_number }}
#          hide_and_recreate: true
#          hide_classify: "OUTDATED"
#          message: |
#            ## 📖 Doc Preview CI
#
#            Preview removed because the pull request was closed.