Fix comment and manual dispatch triggered build jobs

.circleci/config.yml

@@ -6,21 +6,40 @@
 # Check for more details: https://circleci.com/docs/2.1/configuration-reference
 version: 2.1
 
+# in addition to the default circleCI triggering, we have a GitHub Action:
+# .github/triggered_target_build.yml 
+# This Action has a job that uses CircleCI-Public/trigger-circleci-pipeline-action.
+# This allows triggering a CircleCI pipeline from any event on GitHub with GitHub Actions.
+# Right now we are using comments on PRs to trigger the workflow "triggered-by-pr-comment"
+# See: https://github.com/CircleCI-Public/trigger-circleci-pipeline-action/blob/main/README.md
+parameters:
+  GHA_Actor:
+    type: string
+    default: ""
+  GHA_Action:
+    type: string
+    default: ""
+  GHA_Event:
+    type: string
+    default: ""
+  GHA_Meta:
+    type: string
+    default: ""
+
 # Orbs are reusable packages of CircleCI configuration that you may share across projects.
 # See: https://circleci.com/docs/2.1/orb-intro/
 orbs:
   python: circleci/[email protected]
 
-# parameterize the make target used for build, passed in from build_trigger.yml action
-parameters:
-  make_target:
-    type: string
-    default: "slimfast"
-
 jobs:
   build-docs:
     docker:
       - image: cimg/python:3.10.17
+    parameters:
+      # Set make target for the job
+      make_target:
+        type: string
+        default: slimfast
     steps:
       - checkout:
           path: docs
@@ -47,7 +66,7 @@ jobs:
           command: |
             . .venv/bin/activate
             cd docs
-            xvfb-run --auto-servernum make << pipeline.parameters.make_target >>
+            xvfb-run --auto-servernum make << parameters.make_target >>
           environment:
             PIP_CONSTRAINT: ../napari/resources/constraints/constraints_py3.10_docs.txt
       - store_artifacts:
@@ -58,5 +77,24 @@ jobs:
             - docs/docs/_build/html/
 workflows:
   build-docs:
+    # this workflow is triggered automatically by default
+    # so we want to prevent it from triggering when triggering
+    # via CircleCI-Public/trigger-circleci-pipeline-action
+    # which always passes the GHA_Meta parameter
+    # this prevents double triggers
+    when:
+      not: << pipeline.parameters.GHA_Meta >>
     jobs:
       - build-docs
+  # Run this workflow when a PR comment triggers a docs build for `make` target
+  triggered-by-pr-comment:
+    when:
+      or:
+        - equal: ["slimfast", << pipeline.parameters.GHA_Meta >>]
+        - equal: ["slimgallery", << pipeline.parameters.GHA_Meta >>]
+        - equal: ["docs", << pipeline.parameters.GHA_Meta >>]
+        - equal: ["html", << pipeline.parameters.GHA_Meta >>]
+        - equal: ["html-noplot", << pipeline.parameters.GHA_Meta >>]
+    jobs:
+      - build-docs:
+          make_target: << pipeline.parameters.GHA_Meta >>

.github/workflows/build_docs.yml

@@ -5,19 +5,23 @@ name: Build PR Docs
 on:
   pull_request:
     branches:
-        - main
+      - main
   workflow_dispatch:
     inputs:
       make_target:
         description: "Enter make target: html html-noplot docs slimfast slimgallery"
         type: string
-        default: 'slimfast'
+        default: "slimfast"
   workflow_call:
     inputs:
       make_target:
         description: "Enter make target: html html-noplot docs slimfast slimgallery"
         type: string
-        default: 'slimfast'
+        default: "slimfast"
+      pr_ref:
+        description: "PR branch reference"
+        type: string
+        required: false
 
 concurrency:
   group: ${{ github.workflow }}-${{ github.ref }}
@@ -33,6 +37,7 @@ jobs:
         with:
           # Check out to  '/home/runner/work/docs/docs/docs'
           path: docs
+          ref: ${{ inputs.pr_ref || github.ref }}
 
       - name: Clone main repo
         uses: actions/checkout@v4
@@ -70,7 +75,7 @@ jobs:
           GOOGLE_CALENDAR_API_KEY: ${{ secrets.GOOGLE_CALENDAR_API_KEY }}
           PIP_CONSTRAINT: ${{ github.workspace }}/napari/resources/constraints/constraints_py3.10_docs.txt
         with:
-          run:  make -C docs ${{ github.event_name == 'pull_request' && 'slimfast' || inputs.make_target }}
+          run: make -C docs ${{ inputs.make_target || 'slimfast' }}
           # skipping setup stops the action from running the default (tiling) window manager
           # the window manager is not necessary for docs builds at this time and it was causing
           # problems with screenshots (https://github.com/napari/docs/issues/285)

.github/workflows/triggered_target_build.yml

@@ -0,0 +1,121 @@
+name: Trigger target build of docs
+# This workflow can be started either by commenting on a pull request or by using workflow_dispatch manually.
+# You can specify a `make` target to build the documentation for a specific branch or pull request.
+# If started by a comment, the workflow runs on the PR branch and updates the PR status.
+# Note: This workflow runs only once per trigger and does not execute on every push to the PR branch.
+# This workflow triggers both the CircleCI doc build, using CircleCI-Public/trigger-circleci-pipeline-action.
+# as well as an artifact build using the reusable workflow: .github/build_docs.yml
+
+on:
+  issue_comment:
+    types: [created]
+  workflow_dispatch:
+    inputs:
+      make_target:
+        description: "Enter make target: html html-noplot docs slimfast slimgallery"
+        type: string
+        default: "slimfast"
+
+permissions:
+  contents: read
+  issues: write
+  pull-requests: write
+  statuses: write
+
+jobs:
+  determine-make-target:
+    runs-on: ubuntu-latest
+    outputs:
+      target: ${{ steps.determine-make-target.outputs.target }}
+      pr_ref: ${{ steps.get-pr-info.outputs.pr_ref }}
+      pr_sha: ${{ steps.get-pr-info.outputs.pr_sha }}
+    if: |
+      (github.event_name == 'issue_comment' &&
+        github.event.issue.pull_request != '' &&
+        contains(github.event.comment.body, '@napari-bot make')) ||
+      github.event_name == 'workflow_dispatch'
+    steps:
+      - name: Add eyes reaction
+        # If triggered by comment, show that workflow has started
+        if: github.event_name == 'issue_comment'
+        uses: actions/github-script@v7
+        with:
+          script: |
+            await github.rest.reactions.createForIssueComment({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              comment_id: context.payload.comment.id,
+              content: 'eyes'
+            });
+
+      - name: Determine make target from comment or input
+        id: determine-make-target
+        env:
+          COMMENT_BODY: ${{ github.event.comment.body }}
+        run: |
+          ALLOWED_TARGETS="html html-noplot docs slimfast slimgallery"
+
+          if [ "${{ github.event_name }}" = "workflow_dispatch" ]; then
+            TARGET="${{ github.event.inputs.make_target }}"
+          else
+            TARGET=$(echo "$COMMENT_BODY" | grep -oP '(?<=@napari-bot make\s)\w+' || echo "slimfast")
+          fi
+
+          if ! echo "$ALLOWED_TARGETS" | grep -qw "$TARGET"; then
+            echo "::error::Invalid target '$TARGET'. Allowed: $ALLOWED_TARGETS"
+            exit 1
+          fi
+
+          echo "target=$TARGET" >> "$GITHUB_OUTPUT"
+
+      - name: Get PR details
+        # issue_comment is run from the main branch context so
+        # extract PR number and branch name from issue_comment event
+        if: github.event_name == 'issue_comment'
+        id: get-pr-info
+        uses: actions/github-script@v7
+        with:
+          script: |
+            const pr = await github.rest.pulls.get({
+              owner: context.repo.owner,
+              repo: context.repo.repo,
+              pull_number: context.issue.number
+            });
+            core.setOutput('pr_ref', pr.data.head.ref);
+            core.setOutput('pr_sha', pr.data.head.sha);
+
+  trigger-circleci:
+    needs: determine-make-target
+    runs-on: ubuntu-latest
+    steps:
+      - name: Run CircleCI pipeline
+        uses: CircleCI-Public/[email protected]
+        with:
+          GHA_Meta: ${{ needs.determine-make-target.outputs.target }}
+          target-branch: ${{ needs.determine-make-target.outputs.pr_ref || github.ref_name }}
+        env:
+          CCI_TOKEN: ${{ secrets.CIRCLECI_TOKEN }}
+
+  trigger-artifact-build:
+    needs: determine-make-target
+    uses: ./.github/workflows/build_docs.yml
+    with:
+      make_target: ${{ needs.determine-make-target.outputs.target }}
+      pr_ref: ${{ needs.determine-make-target.outputs.pr_ref || github.ref_name }}
+
+  report-artifact-status:
+    # reusable workflows can't be a step in a job
+    # so to get the status of the artifact build, we need a separate job
+    needs: [determine-make-target, trigger-artifact-build]
+    runs-on: ubuntu-latest
+    if: always() && github.event_name == 'issue_comment' && needs.trigger-artifact-build.result != 'skipped'
+    steps:
+      - name: Set build job status
+        uses: myrotvorets/set-commit-status-action@master
+        with:
+          sha: ${{ needs.determine-make-target.outputs.pr_sha }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          status: ${{ needs.trigger-artifact-build.result }}
+          context: "Docs Artifact Build: ${{ needs.determine-make-target.outputs.target }}"
+          description: ${{ needs.trigger-artifact-build.result == 'success' && 'Documentation built successfully' || 'Documentation build failed' }}
+          targetUrl: ${{ github.server_url }}/${{ github.repository }}/actions/runs/${{ github.run_id }}