Issue GitHub warnings for Sphinx undefined references in changed files

.github/workflows/doc.yml

@@ -54,6 +54,19 @@ jobs:
         name: doc-html
         path: Doc/build/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/library/cgi.rst

@@ -102,7 +102,7 @@ produced by :mod:`cgitb` provide information that can save you a lot of time in
 tracking down bugs.  You can always remove the ``cgitb`` line later when you
 have tested your script and are confident that it works correctly.
 
-To get at submitted form data, use the :class:`FieldStorage` class. If the form
+To get at submitted form data use the :class:`FieldStorage` class. If the form
 contains non-ASCII characters, use the *encoding* keyword parameter set to the
 value of the encoding defined for the document. It is usually contained in the
 META tag in the HEAD section of the HTML document or by the

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)