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

[hugovk]

https://github.com/python/cpython/commit/f192a558f538489ad1be30aa145e71d942798d1c
commit: f192a558f538489ad1be30aa145e71d942798d1c
branch: main
author: Hugo van Kemenade <hugovk at users.noreply.github.com>
committer: hugovk <hugovk at users.noreply.github.com>
date: 2023-03-30T21:03:50+03:00
summary:

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

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

files:
A Doc/tools/clean-files.txt
A Doc/tools/touch-clean-files.py
M .github/workflows/doc.yml
M Doc/library/gc.rst

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 29387d30d5a2..314a7da647ff 100644
--- a/.github/workflows/doc.yml
+++ b/.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
 
diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst
index 69a1a8313b75..832ebaf497f3 100644
--- a/Doc/library/gc.rst
+++ b/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
diff --git a/Doc/tools/clean-files.txt b/Doc/tools/clean-files.txt
new file mode 100644
index 000000000000..a6197998f504
--- /dev/null
+++ b/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
diff --git a/Doc/tools/touch-clean-files.py b/Doc/tools/touch-clean-files.py
new file mode 100644
index 000000000000..07f3e509a09f
--- /dev/null
+++ b/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()