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>

diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml
index 29387d30d5a22f80dcd459abc57e99fa62ff4245..314a7da647ff70a0667ba89507a52bd9f9f32835 100644 (file)
--- 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 69a1a8313b7593104986cac131d9c189b1415cc2..832ebaf497f37ab2d3c59d35e9514f8982b6e834 100644 (file)
--- 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 (file)
index 0000000..a619799
--- /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 (file)
index 0000000..07f3e50
--- /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()