ci: skip build-site on PRs without docs/source changes

Add a docs filter to detect-changes and gate build-site so it is
skipped when a PR only touches the workflow YAML file.  Push and
dispatch triggers are unaffected.

Signed-off-by: Ramon Roche <mrpollo@gmail.com>

.github/workflows/docs-orchestrator.yml

@@ -2,7 +2,7 @@
 #
 # Trigger paths:
 #   push (main, release/**)  → metadata-regen → build-site → deploy-aws
-#   pull_request              → detect-changes → pr-metadata-regen → link-check → build-site
+#   pull_request              → detect-changes → pr-metadata-regen → link-check → build-site (if docs/source changed)
 #   workflow_dispatch         → metadata-regen → build-site → deploy-aws
 #
 # Container jobs (pr-metadata-regen, metadata-regen) run in px4-dev image and
@@ -44,6 +44,7 @@ jobs:
     runs-on: ubuntu-latest
     outputs:
       source_changed: ${{ steps.changes.outputs.source }}
+      docs_changed: ${{ steps.changes.outputs.docs }}
     steps:
       - uses: actions/checkout@v4
       - uses: dorny/paths-filter@v3
@@ -55,6 +56,8 @@ jobs:
               - 'msg/**'
               - 'ROMFS/**'
               - 'Tools/module_config/**'
+            docs:
+              - 'docs/**'
 
   # =============================================================================
   # PR Metadata Regen (conditional - only when PR touches source files)
@@ -298,11 +301,12 @@ jobs:
   # =============================================================================
   build-site:
     name: "T3: Build Site"
-    needs: [pr-metadata-regen, metadata-regen, link-check]
+    needs: [detect-changes, pr-metadata-regen, metadata-regen, link-check]
     if: >-
       always() &&
       (needs.metadata-regen.result == 'success' || needs.metadata-regen.result == 'skipped') &&
-      (needs.link-check.result == 'success' || needs.link-check.result == 'skipped')
+      (needs.link-check.result == 'success' || needs.link-check.result == 'skipped') &&
+      (github.event_name != 'pull_request' || needs.detect-changes.outputs.docs_changed == 'true' || needs.detect-changes.outputs.source_changed == 'true')
     permissions:
       contents: read
     runs-on: [runs-on,runner=4cpu-linux-x64,image=ubuntu24-full-x64,"run-id=${{ github.run_id }}",spot=false,extras=s3-cache]

docs/en/test_and_ci/continous_integration.md

@@ -22,7 +22,7 @@ Jobs are organized in tiers, where each tier depends on the previous one complet
 | T2   | PR Metadata    | Yes (conditional) | —               | Builds PX4 SITL and regenerates all auto-generated docs       |
 | T2   | Metadata Sync  | —                 | Yes             | Builds PX4 SITL, regenerates metadata, auto-commits           |
 | T2   | Link Check     | Yes               | —               | Checks for broken links in changed files, posts PR comment    |
-| T3   | Build Site     | Yes (gated on T2) | Yes (after T2)  | Builds the VitePress documentation site                       |
+| T3   | Build Site     | Yes (if docs/source changed) | Yes (after T2)  | Builds the VitePress documentation site                       |
 | T4   | Deploy         | —                 | Yes             | Deploys to AWS S3                                             |
 
 #### Pull Request Flow
@@ -53,7 +53,8 @@ PR Event
                      ▼
 ┌─────────────────────────────────────┐
 │ T3: Build Site (~7-10 min)         │
-│  (only if link check passed)        │
+│  (skipped if only workflow YAML     │
+│   changed — no docs/source changes) │
 │  • Builds VitePress site            │
 │  • Verifies no build errors         │
 └─────────────────┬───────────────────┘
@@ -67,7 +68,7 @@ PR Event
 | **T1: Detect Changes** | ~10s     | Determines if metadata regeneration is needed                                               |
 | **T2: PR Metadata**    | ~10-15m  | Rebuilds PX4 SITL and regenerates all metadata (only if source files changed)               |
 | **T2: Link Check**     | ~30s     | Checks for broken links in changed markdown files and posts a sticky comment to the PR (skipped on fork PRs) |
-| **T3: Build Site**     | ~7-10m   | Builds the VitePress site to verify there are no build errors. Gated on link check passing. |
+| **T3: Build Site**     | ~7-10m   | Builds the VitePress site to verify there are no build errors. Skipped when only the workflow YAML changed (no docs or source changes). |
 
 #### Push / Dispatch Flow (main/release branches)