gh-101100: Fix Sphinx warning in gc.rst and refactor docs clean list (#103116)

Co-authored-by: C.A.M. Gerlach <CAM.Gerlach@Gerlach.CAM>

Author: hugovk

.github/workflows/doc.yml

@@ -72,8 +72,7 @@ jobs:
     - name: 'Build known-good files in nit-picky mode'
       run: |
         # Mark files that must pass nit-picky
-        touch Doc/whatsnew/3.12.rst
-        touch Doc/library/sqlite3.rst
+        python Doc/tools/touch-clean-files.py
         # Build docs with the '-n' (nit-picky) option, convert warnings to errors (-W)
         make -C Doc/ PYTHON=../python SPHINXOPTS="-q -n -W --keep-going" html 2>&1
 

Doc/library/gc.rst

@@ -251,7 +251,7 @@ values but should not rebind them):
       are printed.
 
    .. versionchanged:: 3.4
-      Following :pep:`442`, objects with a :meth:`__del__` method don't end
+      Following :pep:`442`, objects with a :meth:`~object.__del__` method don't end
       up in :attr:`gc.garbage` anymore.
 
 .. data:: callbacks

Doc/tools/clean-files.txt

@@ -0,0 +1,10 @@
+# These files must pass Sphinx nit-picky mode, as tested on the CI
+# via touch-clean-files.py in doc.yml.
+# Add blank lines between files and keep them sorted lexicographically
+# to help avoid merge conflicts.
+
+Doc/library/gc.rst
+
+Doc/library/sqlite3.rst
+
+Doc/whatsnew/3.12.rst

Doc/tools/touch-clean-files.py

@@ -0,0 +1,20 @@
+#!/usr/bin/env python3
+"""
+Touch files that must pass Sphinx nit-picky mode
+so they are rebuilt and we can catch regressions.
+"""
+
+from pathlib import Path
+
+# Input file has blank line between entries to reduce merge conflicts
+with Path("Doc/tools/clean-files.txt").open() as clean_files:
+    CLEAN = [
+        Path(filename.strip())
+        for filename in clean_files
+        if filename.strip() and not filename.startswith("#")
+    ]
+
+print("Touching:")
+for filename in CLEAN:
+    print(filename)
+    filename.touch()