Add more comments to workflows

.github/actions/set-dev-env/action.yml

@@ -1,3 +1,5 @@
+# Reusable action to set our PST development environment
+# DO NOT use for release jobs since we cache dependencies
 name: Setup PST CI environment
 description: Create a PST dev environment
 

.github/workflows/CI.yml

@@ -1,3 +1,4 @@
+# Testing (pytest, a11y-tests), profiling, and coverage checks for PST
 name: continuous-integration
 
 # Concurrency group that uses the workflow name and PR number if available
@@ -23,6 +24,7 @@ on:
   pull_request:
     branches:
       - "*"
+  # allows this to be used as a composite action in other workflows
   workflow_call:
   # allow manual triggering of the workflow, while debugging
   workflow_dispatch:

.github/workflows/coverage.yml

@@ -17,9 +17,11 @@ jobs:
         id: get-run
         uses: octokit/[email protected]
         with:
-          route: GET /repos/${{ github.repository }}/actions/runs/${{ github.event.workflow_run.id }}
+          route: GET /repos/"${REPO}"/actions/runs/"${WORKFLOW_RUN_ID}"
         env:
           GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+          REPO: ${{ github.repository }}
+          WORKFLOW_RUN_ID: ${{ github.event.workflow_run.id }}
 
       # this needs the .coverage file so we download from the CI workflow artifacts
       - name: "Download coverage data 📥"

.github/workflows/docs.yml

@@ -1,4 +1,7 @@
-name: build PST docs
+# This workflow is checks that the documentation can be built across multiple OSes, Python, and Sphinx versions.
+# It also checks for broken links in the documentation and runs Lighthouse audits on the built site.
+
+name: docs-checks
 
 # Concurrency group that uses the workflow name and PR number if available
 # or commit SHA as a fallback. If a new build is triggered under that
@@ -21,6 +24,8 @@ on:
   pull_request:
     branches:
       - "*"
+  # allows this to be used as a composite action in other workflows
+  workflow_call:
   # allow manual triggering of the workflow, while debugging
   workflow_dispatch:
 

.github/workflows/prerelease.yml

@@ -13,6 +13,8 @@ env:
 
 jobs:
   prerelease:
+    # only run this workflow for pydata owned repositories (avoid forks)
+    if: github.repository_owner == 'pydata'
     runs-on: ubuntu-latest
     strategy:
       fail-fast: false

.github/workflows/publish.yml

@@ -16,17 +16,21 @@ permissions:
   contents: read
 
 jobs:
-  # calls our general CI workflow (tests, build docs, etc.)
+  # calls our general CI workflows (tests, coverage, profile, etc.)
   tests:
     uses: ./.github/workflows/CI.yml
     # needed for the coverage action
     permissions:
       contents: write
       pull-requests: write
+  # calls our docs workflow (build docs, check broken links, lighthouse)
+  docs:
+    uses: ./.github/workflows/docs.yml
 
   build-package:
     name: "Build & verify PST package"
-    needs: [tests] # require tests to pass before release runs
+    # require tests and docs to pass before building the package
+    needs: [tests, docs]
     runs-on: ubuntu-latest
     steps:
       - name: "Checkout repository 🛎"