Add doc preview CI (#380)

* add doc preview steps

* add custom preview deploy/undeploy steps

* specify shell

* address PR reviews

.github/actions/doc_preview/action.yml

@@ -0,0 +1,103 @@
+name: Preview or clean up docs built from PRs
+
+# A re-implementation based on the logic of https://github.com/rossjrw/pr-preview-action/blob/41a957c44a456a34718e9bcf825363194db5e6d5/README.md, due to limitations illustrated in NVIDIA/cuda-python#380.
+
+inputs:
+  source-folder:
+    required: true
+    type: string
+
+runs:
+  using: composite
+  steps:
+    # The steps below are executed only when testing in a PR.
+    # Note: the PR previews will be removed once merged to main (see below)
+    - name: Get PR info
+      if: ${{ github.ref_name != 'main' }}
+      uses: nv-gha-runners/get-pr-info@main
+      id: get-pr-info
+
+    - name: Extract PR number from info
+      if: ${{ github.ref_name != 'main' }}
+      shell: bash --noprofile --norc -xeuo pipefail {0}
+      run: |
+        PR_NUMBER="${{ fromJSON(steps.get-pr-info.outputs.pr-info).number }}"
+        if [[ "$PR_NUMBER" == "" ]]; then
+          echo "cannot extract PR number"
+          exit 1
+        else
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+        fi
+    
+    - name: Deploy doc preview
+      if: ${{ github.ref_name != 'main' }}
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        git-config-name: cuda-python-bot
+        git-config-email: [email protected]
+        folder: ${{ inputs.source-folder }}
+        target-folder: docs/pr-preview/pr-${{ env.PR_NUMBER }}/
+        commit-message: "Deploy doc preview for PR ${{ env.PR_NUMBER }} (${{ github.sha }})"
+
+    - name: Leave a comment after deployment
+      if: ${{ github.ref_name != 'main' }}
+      uses: marocchino/sticky-pull-request-comment@v2
+      with:
+        header: pr-preview
+        number: ${{ env.PR_NUMBER }}
+        skip_unchanged: true
+        message: |
+          Doc Preview CI
+          :---:
+          | <p></p> :rocket: View preview at <br> https://nvidia.github.io/cuda-python/pr-preview/pr-${{ env.PR_NUMBER }}/ <br><br>
+          | <h6><br> Preview will be ready when the GitHub Pages deployment is complete. <br><br></h6>
+    
+    # The steps below are executed only when building on main.
+    - name: Get PR data
+      if: ${{ github.ref_name == 'main' }}
+      uses: actions/github-script@v7
+      id: get-pr-data
+      with:
+        script: |
+          return (
+            await github.rest.repos.listPullRequestsAssociatedWithCommit({
+              commit_sha: context.sha,
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+            })
+          ).data[0];
+    
+    - name: Extract PR number from data
+      if: ${{ github.ref_name == 'main' }}
+      shell: bash --noprofile --norc -xeuo pipefail {0}
+      run: |
+        PR_NUMBER="${{ fromJSON(steps.get-pr-data.outputs.result).number }}"
+        if [[ "$PR_NUMBER" == "" ]]; then
+          echo "cannot extract PR number"
+          exit 1
+        else
+          echo "PR_NUMBER=$PR_NUMBER" >> $GITHUB_ENV
+        fi
+    
+    - name: Remove doc preview
+      if: ${{ github.ref_name == 'main' }}
+      uses: JamesIves/github-pages-deploy-action@v4
+      with:
+        git-config-name: cuda-python-bot
+        git-config-email: [email protected]
+        folder: ${{ inputs.source-folder }}
+        target-folder: docs/pr-preview/pr-${{ env.PR_NUMBER }}/
+        commit-message: "Clean up doc preview for PR ${{ env.PR_NUMBER }} (${{ github.sha }})"
+
+    - name: Leave a comment after removal
+      if: ${{ github.ref_name == 'main' }}
+      uses: marocchino/sticky-pull-request-comment@v2
+      with:
+        header: pr-preview
+        number: ${{ env.PR_NUMBER }}
+        hide_and_recreate: true
+        hide_classify: "OUTDATED"
+        message: |
+          Doc Preview CI
+          :---:
+          Preview removed because the pull request was closed or merged.

.github/workflows/build-and-test.yml

@@ -263,6 +263,7 @@ jobs:
     permissions:
       id-token: write
       contents: write
+      pull-requests: write
     needs:
       - build
     secrets: inherit

.github/workflows/build-docs.yml

@@ -50,7 +50,6 @@ jobs:
       # WAR: Building the doc currently requires CTK installed (NVIDIA/cuda-python#326,327)
       - name: Set up mini CTK
         uses: ./.github/actions/fetch_ctk
-        continue-on-error: false
         with:
           host-platform: linux-64
           cuda-version: ${{ inputs.build-ctk-ver }}
@@ -126,22 +125,29 @@ jobs:
           mkdir -p artifacts/docs
           mv cuda_python/docs/build/html/* artifacts/docs/
 
-      # Note: currently this is only for manual inspection. This step will become
-      # required once we switch to use GHA for doc deployment (see the bottom).
+          # create an empty folder for removal use
+          mkdir -p artifacts/empty_docs
+
+      # TODO: Consider removing this step?
       - name: Upload doc artifacts
         uses: actions/upload-pages-artifact@v3
         with:
           path: artifacts/
           retention-days: 3
 
-      # The step below is not executed unless when building on main.
+      - name: Deploy or clean up doc preview
+        uses: ./.github/actions/doc_preview
+        with:
+          source-folder: ${{ (github.ref_name != 'main' && 'artifacts/docs') ||
+                              'artifacts/empty_docs' }}
+
       - name: Deploy doc update
-        if: ${{ github.ref_name == 'main' && success() }}
+        if: ${{ github.ref_name == 'main' }}
         uses: JamesIves/github-pages-deploy-action@v4
         with:
-          folder: artifacts/docs/
           git-config-name: cuda-python-bot
           git-config-email: [email protected]
+          folder: artifacts/docs/
           target-folder: docs/
           commit-message: "Deploy latest docs: ${{ github.sha }}"
           clean: false