Only run linkcheck for changed source files in PRs

Author: JoergAtGithub

.github/workflows/sphinx.yml

@@ -11,16 +11,28 @@ jobs:
     steps:
     - name: Clone repository
       uses: actions/checkout@v6
+      with:
+        fetch-depth: ${{ github.event_name == 'pull_request' && 0 || 1 }}
     - name: Set up Python
       uses: actions/setup-python@v6
       with:
         python-version: '3.13'
+    - name: Get changed source files
+      id: changed
+      if: github.event_name == 'pull_request'
+      env:
+        GITHUB_EVENT_NAME: ${{ github.event_name }}
+        PR_BASE_SHA: ${{ github.event.pull_request.base.sha }}
+        PUSH_BEFORE_SHA: ${{ github.event.before }}
+      run: python tools/list_changed_source_files.py
     - name: Install Python dependencies
+      if: github.event_name == 'push' || steps.changed.outputs.files != ''
       run: |
         python -m pip install --upgrade pip
         python -m pip install -r requirements.txt
     - name: Check for broken links
-      run: sphinx-build -q --color -b linkcheck source build
+      if: github.event_name == 'push' || steps.changed.outputs.files != ''
+      run: sphinx-build -q --color -b linkcheck source build ${{ steps.changed.outputs.files }}
 
   build:
     name: Build Check

tools/list_changed_source_files.py

@@ -0,0 +1,49 @@
+import os
+import subprocess
+import sys
+
+SOURCE_SUFFIXES = {".rst", ".md"}
+
+
+def get_changed_source_files() -> list[str]:
+    event_name = os.environ.get("GITHUB_EVENT_NAME", "")
+    if event_name != "pull_request":
+        return []
+
+    baseCommitSHA = os.environ.get("PR_BASE_SHA", "")
+    if not baseCommitSHA or baseCommitSHA == "0" * 40:
+        return []
+
+    filesDifferFromBaseCommit = subprocess.run(
+        # "source/" matches all subdirectories recursively
+        ["git", "diff", "--name-only", baseCommitSHA, "HEAD", "--", "source/"],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+
+    return [
+        line.removeprefix("source/")
+        for line in filesDifferFromBaseCommit.stdout.splitlines()
+        if any(line.endswith(suffix) for suffix in SOURCE_SUFFIXES)
+    ]
+
+
+def main() -> None:
+    files = get_changed_source_files()
+    github_output = os.environ.get("GITHUB_OUTPUT")
+
+    if github_output:
+        with open(github_output, "a", encoding="utf-8") as f:
+            f.write(f"files={' '.join(files)}\n")
+
+    if files:
+        print(f"Changed source files: {files}")
+    else:
+        print("No source files changed.")
+
+    sys.exit(0)
+
+
+if __name__ == "__main__":
+    main()