gh-101100: Use list of 'dirty' docs, with warnings, instead of a clean list (#103191)

Co-authored-by: Alex Waygood <Alex.Waygood@Gmail.com>

3 files changed, 332 insertions, 371 deletions

diff --git a/Doc/tools/.nitignore b/Doc/tools/.nitignore
new file mode 100644
index 0000000..f6fe8df
--- /dev/null
+++ b/Doc/tools/.nitignore
@@ -0,0 +1,304 @@
+# All RST files under Doc/ -- except these -- 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/c-api/allocation.rst
+Doc/c-api/apiabiversion.rst
+Doc/c-api/arg.rst
+Doc/c-api/bool.rst
+Doc/c-api/buffer.rst
+Doc/c-api/bytes.rst
+Doc/c-api/call.rst
+Doc/c-api/capsule.rst
+Doc/c-api/cell.rst
+Doc/c-api/code.rst
+Doc/c-api/codec.rst
+Doc/c-api/complex.rst
+Doc/c-api/conversion.rst
+Doc/c-api/datetime.rst
+Doc/c-api/descriptor.rst
+Doc/c-api/dict.rst
+Doc/c-api/exceptions.rst
+Doc/c-api/file.rst
+Doc/c-api/float.rst
+Doc/c-api/gcsupport.rst
+Doc/c-api/import.rst
+Doc/c-api/init.rst
+Doc/c-api/init_config.rst
+Doc/c-api/intro.rst
+Doc/c-api/iterator.rst
+Doc/c-api/long.rst
+Doc/c-api/mapping.rst
+Doc/c-api/marshal.rst
+Doc/c-api/memory.rst
+Doc/c-api/memoryview.rst
+Doc/c-api/module.rst
+Doc/c-api/none.rst
+Doc/c-api/object.rst
+Doc/c-api/refcounting.rst
+Doc/c-api/sequence.rst
+Doc/c-api/set.rst
+Doc/c-api/stable.rst
+Doc/c-api/structures.rst
+Doc/c-api/sys.rst
+Doc/c-api/tuple.rst
+Doc/c-api/type.rst
+Doc/c-api/typehints.rst
+Doc/c-api/typeobj.rst
+Doc/c-api/unicode.rst
+Doc/c-api/veryhigh.rst
+Doc/c-api/weakref.rst
+Doc/extending/embedding.rst
+Doc/extending/extending.rst
+Doc/extending/newtypes.rst
+Doc/extending/newtypes_tutorial.rst
+Doc/faq/design.rst
+Doc/faq/extending.rst
+Doc/faq/gui.rst
+Doc/faq/library.rst
+Doc/faq/programming.rst
+Doc/glossary.rst
+Doc/howto/argparse.rst
+Doc/howto/curses.rst
+Doc/howto/descriptor.rst
+Doc/howto/enum.rst
+Doc/howto/functional.rst
+Doc/howto/instrumentation.rst
+Doc/howto/isolating-extensions.rst
+Doc/howto/logging-cookbook.rst
+Doc/howto/logging.rst
+Doc/howto/regex.rst
+Doc/howto/sorting.rst
+Doc/howto/unicode.rst
+Doc/howto/urllib2.rst
+Doc/install/index.rst
+Doc/library/2to3.rst
+Doc/library/__future__.rst
+Doc/library/_thread.rst
+Doc/library/abc.rst
+Doc/library/aifc.rst
+Doc/library/argparse.rst
+Doc/library/ast.rst
+Doc/library/asyncio-dev.rst
+Doc/library/asyncio-eventloop.rst
+Doc/library/asyncio-extending.rst
+Doc/library/asyncio-future.rst
+Doc/library/asyncio-policy.rst
+Doc/library/asyncio-stream.rst
+Doc/library/asyncio-subprocess.rst
+Doc/library/asyncio-task.rst
+Doc/library/audioop.rst
+Doc/library/bdb.rst
+Doc/library/bisect.rst
+Doc/library/bz2.rst
+Doc/library/calendar.rst
+Doc/library/cgi.rst
+Doc/library/chunk.rst
+Doc/library/cmath.rst
+Doc/library/cmd.rst
+Doc/library/code.rst
+Doc/library/codecs.rst
+Doc/library/codeop.rst
+Doc/library/collections.abc.rst
+Doc/library/collections.rst
+Doc/library/compileall.rst
+Doc/library/concurrent.futures.rst
+Doc/library/concurrent.rst
+Doc/library/configparser.rst
+Doc/library/constants.rst
+Doc/library/contextlib.rst
+Doc/library/copy.rst
+Doc/library/csv.rst
+Doc/library/ctypes.rst
+Doc/library/curses.ascii.rst
+Doc/library/curses.rst
+Doc/library/dataclasses.rst
+Doc/library/datetime.rst
+Doc/library/dbm.rst
+Doc/library/decimal.rst
+Doc/library/devmode.rst
+Doc/library/difflib.rst
+Doc/library/dis.rst
+Doc/library/doctest.rst
+Doc/library/email.charset.rst
+Doc/library/email.compat32-message.rst
+Doc/library/email.encoders.rst
+Doc/library/email.errors.rst
+Doc/library/email.generator.rst
+Doc/library/email.headerregistry.rst
+Doc/library/email.message.rst
+Doc/library/email.mime.rst
+Doc/library/email.parser.rst
+Doc/library/email.policy.rst
+Doc/library/enum.rst
+Doc/library/exceptions.rst
+Doc/library/faulthandler.rst
+Doc/library/fcntl.rst
+Doc/library/filecmp.rst
+Doc/library/fileinput.rst
+Doc/library/fractions.rst
+Doc/library/ftplib.rst
+Doc/library/functions.rst
+Doc/library/functools.rst
+Doc/library/getopt.rst
+Doc/library/getpass.rst
+Doc/library/gettext.rst
+Doc/library/graphlib.rst
+Doc/library/gzip.rst
+Doc/library/hashlib.rst
+Doc/library/http.client.rst
+Doc/library/http.cookiejar.rst
+Doc/library/http.cookies.rst
+Doc/library/http.server.rst
+Doc/library/idle.rst
+Doc/library/imp.rst
+Doc/library/importlib.resources.abc.rst
+Doc/library/importlib.resources.rst
+Doc/library/importlib.rst
+Doc/library/inspect.rst
+Doc/library/io.rst
+Doc/library/json.rst
+Doc/library/locale.rst
+Doc/library/logging.config.rst
+Doc/library/logging.handlers.rst
+Doc/library/logging.rst
+Doc/library/lzma.rst
+Doc/library/mailbox.rst
+Doc/library/mmap.rst
+Doc/library/msilib.rst
+Doc/library/msvcrt.rst
+Doc/library/multiprocessing.rst
+Doc/library/multiprocessing.shared_memory.rst
+Doc/library/netrc.rst
+Doc/library/nntplib.rst
+Doc/library/numbers.rst
+Doc/library/operator.rst
+Doc/library/optparse.rst
+Doc/library/os.path.rst
+Doc/library/os.rst
+Doc/library/ossaudiodev.rst
+Doc/library/pickle.rst
+Doc/library/pickletools.rst
+Doc/library/pkgutil.rst
+Doc/library/platform.rst
+Doc/library/plistlib.rst
+Doc/library/poplib.rst
+Doc/library/posix.rst
+Doc/library/pprint.rst
+Doc/library/profile.rst
+Doc/library/pty.rst
+Doc/library/py_compile.rst
+Doc/library/pyclbr.rst
+Doc/library/pydoc.rst
+Doc/library/pyexpat.rst
+Doc/library/random.rst
+Doc/library/re.rst
+Doc/library/readline.rst
+Doc/library/reprlib.rst
+Doc/library/resource.rst
+Doc/library/rlcompleter.rst
+Doc/library/sched.rst
+Doc/library/select.rst
+Doc/library/selectors.rst
+Doc/library/shelve.rst
+Doc/library/shutil.rst
+Doc/library/signal.rst
+Doc/library/site.rst
+Doc/library/smtplib.rst
+Doc/library/socket.rst
+Doc/library/socketserver.rst
+Doc/library/ssl.rst
+Doc/library/stat.rst
+Doc/library/stdtypes.rst
+Doc/library/string.rst
+Doc/library/struct.rst
+Doc/library/subprocess.rst
+Doc/library/sunau.rst
+Doc/library/sys.rst
+Doc/library/sys_path_init.rst
+Doc/library/sysconfig.rst
+Doc/library/syslog.rst
+Doc/library/tarfile.rst
+Doc/library/telnetlib.rst
+Doc/library/tempfile.rst
+Doc/library/termios.rst
+Doc/library/test.rst
+Doc/library/textwrap.rst
+Doc/library/threading.rst
+Doc/library/time.rst
+Doc/library/tkinter.rst
+Doc/library/tkinter.scrolledtext.rst
+Doc/library/tkinter.tix.rst
+Doc/library/tkinter.ttk.rst
+Doc/library/traceback.rst
+Doc/library/tty.rst
+Doc/library/turtle.rst
+Doc/library/unittest.mock-examples.rst
+Doc/library/unittest.mock.rst
+Doc/library/unittest.rst
+Doc/library/urllib.error.rst
+Doc/library/urllib.parse.rst
+Doc/library/urllib.request.rst
+Doc/library/uuid.rst
+Doc/library/wave.rst
+Doc/library/weakref.rst
+Doc/library/webbrowser.rst
+Doc/library/winreg.rst
+Doc/library/winsound.rst
+Doc/library/wsgiref.rst
+Doc/library/xdrlib.rst
+Doc/library/xml.dom.minidom.rst
+Doc/library/xml.dom.pulldom.rst
+Doc/library/xml.dom.rst
+Doc/library/xml.etree.elementtree.rst
+Doc/library/xml.rst
+Doc/library/xml.sax.handler.rst
+Doc/library/xml.sax.reader.rst
+Doc/library/xml.sax.rst
+Doc/library/xml.sax.utils.rst
+Doc/library/xmlrpc.client.rst
+Doc/library/xmlrpc.rst
+Doc/library/xmlrpc.server.rst
+Doc/library/zlib.rst
+Doc/license.rst
+Doc/reference/compound_stmts.rst
+Doc/reference/datamodel.rst
+Doc/reference/expressions.rst
+Doc/reference/import.rst
+Doc/reference/lexical_analysis.rst
+Doc/reference/simple_stmts.rst
+Doc/tutorial/appendix.rst
+Doc/tutorial/classes.rst
+Doc/tutorial/controlflow.rst
+Doc/tutorial/datastructures.rst
+Doc/tutorial/errors.rst
+Doc/tutorial/inputoutput.rst
+Doc/tutorial/interactive.rst
+Doc/tutorial/introduction.rst
+Doc/tutorial/modules.rst
+Doc/tutorial/stdlib2.rst
+Doc/using/cmdline.rst
+Doc/using/configure.rst
+Doc/using/unix.rst
+Doc/using/windows.rst
+Doc/whatsnew/2.0.rst
+Doc/whatsnew/2.1.rst
+Doc/whatsnew/2.2.rst
+Doc/whatsnew/2.3.rst
+Doc/whatsnew/2.4.rst
+Doc/whatsnew/2.5.rst
+Doc/whatsnew/2.6.rst
+Doc/whatsnew/2.7.rst
+Doc/whatsnew/3.0.rst
+Doc/whatsnew/3.1.rst
+Doc/whatsnew/3.2.rst
+Doc/whatsnew/3.3.rst
+Doc/whatsnew/3.4.rst
+Doc/whatsnew/3.5.rst
+Doc/whatsnew/3.6.rst
+Doc/whatsnew/3.7.rst
+Doc/whatsnew/3.8.rst
+Doc/whatsnew/3.9.rst
+Doc/whatsnew/3.10.rst
+Doc/whatsnew/3.11.rst
diff --git a/Doc/tools/clean-files.txt b/Doc/tools/clean-files.txt
deleted file mode 100644
index baef7c2..0000000
--- a/Doc/tools/clean-files.txt
+++ /dev/null
@@ -1,366 +0,0 @@
-# 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/about.rst
-
-Doc/bugs.rst
-
-Doc/c-api/abstract.rst
-
-Doc/c-api/bytearray.rst
-
-Doc/c-api/concrete.rst
-
-Doc/c-api/contextvars.rst
-
-Doc/c-api/coro.rst
-
-Doc/c-api/frame.rst
-
-Doc/c-api/function.rst
-
-Doc/c-api/gen.rst
-
-Doc/c-api/index.rst
-
-Doc/c-api/iter.rst
-
-Doc/c-api/list.rst
-
-Doc/c-api/method.rst
-
-Doc/c-api/number.rst
-
-Doc/c-api/objbuffer.rst
-
-Doc/c-api/objimpl.rst
-
-Doc/c-api/reflection.rst
-
-Doc/c-api/slice.rst
-
-Doc/c-api/utilities.rst
-
-Doc/contents.rst
-
-Doc/copyright.rst
-
-Doc/distributing/index.rst
-
-Doc/extending/building.rst
-
-Doc/extending/index.rst
-
-Doc/extending/windows.rst
-
-Doc/faq/general.rst
-
-Doc/faq/index.rst
-
-Doc/faq/installed.rst
-
-Doc/faq/windows.rst
-
-Doc/howto/annotations.rst
-
-Doc/howto/clinic.rst
-
-Doc/howto/cporting.rst
-
-Doc/howto/index.rst
-
-Doc/howto/ipaddress.rst
-
-Doc/howto/perf_profiling.rst
-
-Doc/howto/pyporting.rst
-
-Doc/howto/sockets.rst
-
-Doc/installing/index.rst
-
-Doc/library/__main__.rst
-
-Doc/library/allos.rst
-
-Doc/library/archiving.rst
-
-Doc/library/array.rst
-
-Doc/library/asyncio-api-index.rst
-
-Doc/library/asyncio-exceptions.rst
-
-Doc/library/asyncio-llapi-index.rst
-
-Doc/library/asyncio-platforms.rst
-
-Doc/library/asyncio-protocol.rst
-
-Doc/library/asyncio-queue.rst
-
-Doc/library/asyncio-runner.rst
-
-Doc/library/asyncio-sync.rst
-
-Doc/library/asyncio.rst
-
-Doc/library/atexit.rst
-
-Doc/library/audit_events.rst
-
-Doc/library/base64.rst
-
-Doc/library/binary.rst
-
-Doc/library/binascii.rst
-
-Doc/library/builtins.rst
-
-Doc/library/cgitb.rst
-
-Doc/library/colorsys.rst
-
-Doc/library/concurrency.rst
-
-Doc/library/contextvars.rst
-
-Doc/library/copyreg.rst
-
-Doc/library/crypt.rst
-
-Doc/library/crypto.rst
-
-Doc/library/curses.panel.rst
-
-Doc/library/custominterp.rst
-
-Doc/library/datatypes.rst
-
-Doc/library/debug.rst
-
-Doc/library/development.rst
-
-Doc/library/dialog.rst
-
-Doc/library/distribution.rst
-
-Doc/library/email.contentmanager.rst
-
-Doc/library/email.examples.rst
-
-Doc/library/email.header.rst
-
-Doc/library/email.iterators.rst
-
-Doc/library/email.rst
-
-Doc/library/email.utils.rst
-
-Doc/library/ensurepip.rst
-
-Doc/library/errno.rst
-
-Doc/library/fileformats.rst
-
-Doc/library/filesys.rst
-
-Doc/library/fnmatch.rst
-
-Doc/library/frameworks.rst
-
-Doc/library/functional.rst
-
-Doc/library/gc.rst
-
-Doc/library/glob.rst
-
-Doc/library/grp.rst
-
-Doc/library/heapq.rst
-
-Doc/library/hmac.rst
-
-Doc/library/html.entities.rst
-
-Doc/library/html.parser.rst
-
-Doc/library/html.rst
-
-Doc/library/http.rst
-
-Doc/library/i18n.rst
-
-Doc/library/imaplib.rst
-
-Doc/library/imghdr.rst
-
-Doc/library/importlib.metadata.rst
-
-Doc/library/index.rst
-
-Doc/library/internet.rst
-
-Doc/library/intro.rst
-
-Doc/library/ipaddress.rst
-
-Doc/library/ipc.rst
-
-Doc/library/itertools.rst
-
-Doc/library/keyword.rst
-
-Doc/library/language.rst
-
-Doc/library/linecache.rst
-
-Doc/library/mailcap.rst
-
-Doc/library/markup.rst
-
-Doc/library/marshal.rst
-
-Doc/library/math.rst
-
-Doc/library/mimetypes.rst
-
-Doc/library/mm.rst
-
-Doc/library/modulefinder.rst
-
-Doc/library/modules.rst
-
-Doc/library/netdata.rst
-
-Doc/library/nis.rst
-
-Doc/library/numeric.rst
-
-Doc/library/pathlib.rst
-
-Doc/library/pdb.rst
-
-Doc/library/persistence.rst
-
-Doc/library/pipes.rst
-
-Doc/library/pwd.rst
-
-Doc/library/python.rst
-
-Doc/library/queue.rst
-
-Doc/library/quopri.rst
-
-Doc/library/runpy.rst
-
-Doc/library/secrets.rst
-
-Doc/library/security_warnings.rst
-
-Doc/library/shlex.rst
-
-Doc/library/sndhdr.rst
-
-Doc/library/spwd.rst
-
-Doc/library/sqlite3.rst
-
-Doc/library/statistics.rst
-
-Doc/library/stringprep.rst
-
-Doc/library/superseded.rst
-
-Doc/library/symtable.rst
-
-Doc/library/tabnanny.rst
-
-Doc/library/text.rst
-
-Doc/library/timeit.rst
-
-Doc/library/tk.rst
-
-Doc/library/tkinter.colorchooser.rst
-
-Doc/library/tkinter.dnd.rst
-
-Doc/library/tkinter.font.rst
-
-Doc/library/tkinter.messagebox.rst
-
-#Doc/library/token.rst
-
-Doc/library/tokenize.rst
-
-Doc/library/tomllib.rst
-
-Doc/library/trace.rst
-
-Doc/library/tracemalloc.rst
-
-Doc/library/types.rst
-
-Doc/library/typing.rst
-
-Doc/library/unicodedata.rst
-
-Doc/library/unix.rst
-
-Doc/library/urllib.robotparser.rst
-
-Doc/library/urllib.rst
-
-Doc/library/uu.rst
-
-Doc/library/venv.rst
-
-Doc/library/warnings.rst
-
-Doc/library/windows.rst
-
-Doc/library/zipapp.rst
-
-Doc/library/zipfile.rst
-
-Doc/library/zipimport.rst
-
-Doc/library/zoneinfo.rst
-
-Doc/reference/executionmodel.rst
-
-Doc/reference/grammar.rst
-
-Doc/reference/index.rst
-
-Doc/reference/introduction.rst
-
-Doc/reference/toplevel_components.rst
-
-Doc/tutorial/appetite.rst
-
-Doc/tutorial/floatingpoint.rst
-
-Doc/tutorial/index.rst
-
-Doc/tutorial/interpreter.rst
-
-Doc/tutorial/stdlib.rst
-
-Doc/tutorial/venv.rst
-
-Doc/tutorial/whatnow.rst
-
-Doc/using/editors.rst
-
-Doc/using/index.rst
-
-Doc/using/mac.rst
-
-Doc/whatsnew/3.12.rst
-
-Doc/whatsnew/index.rst
diff --git a/Doc/tools/touch-clean-files.py b/Doc/tools/touch-clean-files.py
index 9f55e94..19bc1be 100644
--- a/Doc/tools/touch-clean-files.py
+++ b/Doc/tools/touch-clean-files.py
@@ -6,16 +6,39 @@ 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 = [
+wrong_directory_msg = "Must run this script from the repo root"
+assert Path("Doc").exists() and Path("Doc").is_dir(), wrong_directory_msg
+
+# Exclude these whether they're dirty or clean,
+# because they trigger a rebuild of dirty files.
+EXCLUDE_FILES = {
+    Path("Doc/whatsnew/changelog.rst"),
+}
+
+# Subdirectories of Doc/ to exclude.
+EXCLUDE_SUBDIRS = {
+    ".env",
+    ".venv",
+    "env",
+    "includes",
+    "venv",
+}
+
+ALL_RST = {
+    rst for rst in Path("Doc/").rglob("*.rst") if rst.parts[1] not in EXCLUDE_SUBDIRS
+}
+
+with Path("Doc/tools/.nitignore").open() as clean_files:
+    DIRTY = {
         Path(filename.strip())
         for filename in clean_files
         if filename.strip() and not filename.startswith("#")
-    ]
+    }
+
+CLEAN = ALL_RST - DIRTY - EXCLUDE_FILES
 
 print("Touching:")
-for filename in CLEAN:
+for filename in sorted(CLEAN):
     print(filename)
     filename.touch()
 print(f"Touched {len(CLEAN)} files")