[3.12] Convert doc.yml workflow to be reusable (GH-103914 + GH-105151) (#107042)

Co-authored-by: Sviatoslav Sydorenko <[email protected]>
Co-authored-by: Adam Turner <[email protected]>
Co-authored-by: Hugo van Kemenade <[email protected]>

(cherry picked from commit 88d14da)
(cherry picked from commit eaa6702)

Author: webknjaz

.github/workflows/build.yml

@@ -28,7 +28,7 @@ permissions:
   contents: read
 
 concurrency:
-  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}
+  group: ${{ github.workflow }}-${{ github.head_ref || github.run_id }}-reusable
   cancel-in-progress: true
 
 jobs:
@@ -37,6 +37,7 @@ jobs:
     runs-on: ubuntu-latest
     timeout-minutes: 10
     outputs:
+      run-docs: ${{ steps.docs-changes.outputs.run-docs || false }}
       run_tests: ${{ steps.check.outputs.run_tests }}
       run_hypothesis: ${{ steps.check.outputs.run_hypothesis }}
       config_hash: ${{ steps.config_hash.outputs.hash }}
@@ -79,6 +80,29 @@ jobs:
         id: config_hash
         run: |
           echo "hash=${{ hashFiles('configure', 'configure.ac', '.github/workflows/build.yml') }}" >> $GITHUB_OUTPUT
+      - name: Get a list of the changed documentation-related files
+        if: github.event_name == 'pull_request'
+        id: changed-docs-files
+        uses: Ana06/[email protected]
+        with:
+          filter: |
+            Doc/**
+            Misc/**
+            .github/workflows/reusable-docs.yml
+          format: csv  # works for paths with spaces
+      - name: Check for docs changes
+        if: >-
+          github.event_name == 'pull_request'
+          && steps.changed-docs-files.outputs.added_modified_renamed != ''
+        id: docs-changes
+        run: |
+          echo "run-docs=true" >> "${GITHUB_OUTPUT}"
+
+  check-docs:
+    name: Docs
+    needs: check_source
+    if: fromJSON(needs.check_source.outputs.run-docs)
+    uses: ./.github/workflows/reusable-docs.yml
 
   check_abi:
     name: 'Check if the ABI has changed'

.github/workflows/doc.yml renamed to .github/workflows/reusable-docs.yml

@@ -1,31 +1,8 @@
 name: Docs
 
 on:
+  workflow_call:
   workflow_dispatch:
-  #push:
-  #  branches:
-  #  - 'main'
-  #  - '3.12'
-  #  - '3.11'
-  #  - '3.10'
-  #  - '3.9'
-  #  - '3.8'
-  #  - '3.7'
-  #  paths:
-  #  - 'Doc/**'
-  pull_request:
-    branches:
-    - 'main'
-    - '3.12'
-    - '3.11'
-    - '3.10'
-    - '3.9'
-    - '3.8'
-    - '3.7'
-    paths:
-    - 'Doc/**'
-    - 'Misc/**'
-    - '.github/workflows/doc.yml'
 
 permissions:
   contents: read
@@ -61,12 +38,14 @@ jobs:
       uses: Ana06/[email protected]
       with:
         filter: "Doc/**"
+        format: csv  # works for paths with spaces
     - name: 'Build changed files in nit-picky mode'
       if: github.event_name == 'pull_request'
       continue-on-error: true
       run: |
+        set -Eeuo pipefail
         # Mark files the pull request modified
-        touch ${{ steps.changed_files.outputs.added_modified }}
+        python Doc/tools/touch-clean-files.py --clean '${{ steps.changed_files.outputs.added_modified }}'
         # Build docs with the '-n' (nit-picky) option; convert warnings to annotations
         make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n --keep-going" html 2>&1 |
             python Doc/tools/warnings-to-gh-actions.py

Doc/tools/touch-clean-files.py

@@ -3,7 +3,9 @@
 Touch files that must pass Sphinx nit-picky mode
 so they are rebuilt and we can catch regressions.
 """
-
+import argparse
+import csv
+import sys
 from pathlib import Path
 
 wrong_directory_msg = "Must run this script from the repo root"
@@ -28,14 +30,33 @@
     rst for rst in Path("Doc/").rglob("*.rst") if rst.parts[1] not in EXCLUDE_SUBDIRS
 }
 
-with Path("Doc/tools/.nitignore").open() as clean_files:
-    DIRTY = {
+
+parser = argparse.ArgumentParser(
+    description=__doc__, formatter_class=argparse.RawDescriptionHelpFormatter
+)
+parser.add_argument("-c", "--clean", help="Comma-separated list of clean files")
+args = parser.parse_args()
+
+if args.clean:
+    clean_files = next(csv.reader([args.clean]))
+    CLEAN = {
         Path(filename.strip())
         for filename in clean_files
-        if filename.strip() and not filename.startswith("#")
+        if Path(filename.strip()).is_file()
     }
-
-CLEAN = ALL_RST - DIRTY - EXCLUDE_FILES
+elif args.clean is not None:
+    print(
+        "Not touching any files: an empty string `--clean` arg value passed.",
+    )
+    sys.exit(0)
+else:
+    with Path("Doc/tools/.nitignore").open() as ignored_files:
+        IGNORED = {
+            Path(filename.strip())
+            for filename in ignored_files
+            if filename.strip() and not filename.startswith("#")
+        }
+    CLEAN = ALL_RST - IGNORED - EXCLUDE_FILES
 
 print("Touching:")
 for filename in sorted(CLEAN):