name: Docs Preview

on:
  pull_request:
  workflow_dispatch:
    inputs:
      pr_number:
        required: true
        type: string

# ensure job runs sequentially so pushing to the preview branch doesn't conflict
concurrency:
  group: ci-docs-preview

# Default to read-only; jobs that need more grant it explicitly.
permissions:
  contents: read

jobs:
  preview_docs:
    permissions:
      contents: write        # peaceiris/actions-gh-pages pushes the preview
      pull-requests: write   # find-comment / create-or-update-comment
    timeout-minutes: 30
    name: Docs preview
    if: github.event_name == 'workflow_dispatch' || github.event.pull_request.head.repo.full_name == github.repository
    runs-on: ubuntu-latest
    env:
      RUSTC_WRAPPER: "sccache"
      SCCACHE_GHA_ENABLED: "on"
      SCCACHE_CACHE_SIZE: "10G"
      PREVIEW_PATH: pr/${{ github.event.pull_request.number || inputs.pr_number }}/docs

    steps:
    - uses: actions/checkout@d23441a48e516b6c34aea4fa41551a30e30af803 # v6.1.0
      with:
        persist-credentials: false
    - uses: dtolnay/rust-toolchain@6c977a6ca4077a0ceb28ffbe03f59d46e9ac8772 # v1
      with:
        toolchain: nightly-2025-10-09
    - name: Install sccache
      uses: mozilla-actions/sccache-action@7d986dd989559c6ecdb630a3fd2557667be217ad # v0.0.9

    - name: Generate Docs
      run: cargo doc --locked --workspace --all-features --no-deps
      env:
        RUSTDOCFLAGS: --cfg docsrs

    - name: Deploy Docs to Preview Branch
      uses: peaceiris/actions-gh-pages@84c30a85c19949d7eee79c4ff27748b70285e453 # v4.1.0
      with:
        github_token: ${{ secrets.GITHUB_TOKEN }}
        publish_dir: ./target/doc/
        destination_dir: ${{ env.PREVIEW_PATH }}
        publish_branch: generated-docs-preview

    - name: Find Docs Comment
      uses: peter-evans/find-comment@b30e6a3c0ed37e7c023ccd3f1db5c6c0b0c23aad # v4.0.0
      id: fc
      with:
        issue-number: ${{ github.event.pull_request.number || inputs.pr_number }}
        comment-author: 'github-actions[bot]'
        body-includes: Documentation for this PR has been generated

    - name: Get current timestamp
      id: get_timestamp
      run: echo "TIMESTAMP=$(date -u +'%Y-%m-%dT%H:%M:%SZ')" >> $GITHUB_ENV

    - name: Create or Update Docs Comment
      uses: peter-evans/create-or-update-comment@e8674b075228eee787fea43ef493e45ece1004c9 # v5.0.0
      with:
        issue-number: ${{ github.event.pull_request.number || inputs.pr_number }}
        comment-id: ${{ steps.fc.outputs.comment-id }}
        body: |
          Documentation for this PR has been generated and is available at: https://${{ github.repository_owner }}.github.io/${{ github.event.repository.name }}/${{ env.PREVIEW_PATH }}/noq/

          Last updated: ${{ env.TIMESTAMP }}
        edit-mode: replace