GHA, Docs: Add PR annotations for failed Sphinx references

Author: encukou

.github/workflows/doc.yml

@@ -53,6 +53,19 @@ jobs:
     - name: 'Build HTML documentation'
       run: make -C Doc/ SPHINXOPTS="-q" SPHINXERRORHANDLING="-W --keep-going" html
 
+    # Add pull request annotations for Sphinx nitpicks (missing references)
+    - name: Get list of changed files
+      id: changed_files
+      uses: jitterbit/get-changed-files@v1
+    - name: 'Build with nitpicks'
+      continue-on-error: true
+      run: |
+        # Mark files the pull request modified
+        touch ${{ steps.changed_files.outputs.added_modified }}
+        # Build docs with the '-n' (nitpicky) option, convert warnings
+        make -C Doc/ PYTHON=../python SPHINXOPTS="-q --keep-going -n" html 2>&1 |
+            python Doc/tools/warnings-to-gh-actions.py
+
   # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release
   doctest:
     name: 'Doctest'

Doc/tools/warnings-to-gh-actions.py

@@ -0,0 +1,24 @@
+#!/usr/bin/env python3
+
+"""Convert Sphinx warning messages to GitHub Actions
+
+Converts lines like:
+    .../Doc/library/cgi.rst:98: WARNING: reference target not found
+to:
+    ::warning file=.../Doc/library/cgi.rst,line=98::reference target not found
+
+Non-matching lines are echoed unchanged.
+
+see: https://docs.github.com/en/actions/using-workflows/workflow-commands-for-github-actions#setting-a-warning-message
+"""
+
+import sys
+import re
+
+pattern = re.compile(r'(?P<file>[^:]+):(?P<line>\d+): WARNING: (?P<msg>.+)')
+
+for line in sys.stdin:
+    if match := pattern.fullmatch(line.strip()):
+        print('::warning file={file},line={line}::{msg}'.format_map(match))
+    else:
+        print(line)