From 198bd9db81c88d0e9aba0107c124c7d8e4ce4813 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 29 Mar 2023 19:32:51 +0300 Subject: [PATCH 1/7] gh-101100: Touch files that must pass Sphinx nit-picky mode --- .github/workflows/doc.yml | 3 +-- Doc/tools/touch-clean-files.py | 17 +++++++++++++++++ 2 files changed, 18 insertions(+), 2 deletions(-) create mode 100644 Doc/tools/touch-clean-files.py diff --git a/.github/workflows/doc.yml b/.github/workflows/doc.yml index 29387d30d5a22f..314a7da647ff70 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/tools/touch-clean-files.py b/Doc/tools/touch-clean-files.py new file mode 100644 index 00000000000000..904ea0e47ae1d6 --- /dev/null +++ b/Doc/tools/touch-clean-files.py @@ -0,0 +1,17 @@ +#!/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 + +CLEAN = [ + "Doc/library/gc.rst", + "Doc/library/sqlite3.rst", + "Doc/whatsnew/3.12.rst", +] +print("Touching:") +for filename in CLEAN: + print(f"{filename}") + Path(filename).touch() From f7b3ccd07fd1964ea6ca9da9ab5eb5d76ffd65c0 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 29 Mar 2023 21:36:32 +0300 Subject: [PATCH 2/7] gh-101100: Fix reference to __del__ in gc.rst --- Doc/library/gc.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/library/gc.rst b/Doc/library/gc.rst index 69a1a8313b7593..832ebaf497f37a 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 From a433b15de87fb4037606af82d04e9e29403e47c8 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 29 Mar 2023 22:11:29 +0300 Subject: [PATCH 3/7] Simplify print Co-authored-by: C.A.M. Gerlach --- Doc/tools/touch-clean-files.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/tools/touch-clean-files.py b/Doc/tools/touch-clean-files.py index 904ea0e47ae1d6..af480bbf49ab9c 100644 --- a/Doc/tools/touch-clean-files.py +++ b/Doc/tools/touch-clean-files.py @@ -13,5 +13,5 @@ ] print("Touching:") for filename in CLEAN: - print(f"{filename}") + print(filename) Path(filename).touch() From a252fb688759f74793d3e63e51ccc883d86609fd Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Wed, 29 Mar 2023 23:04:39 +0300 Subject: [PATCH 4/7] Move cleaned files to text file --- Doc/tools/clean-files.txt | 6 ++++++ Doc/tools/touch-clean-files.py | 13 ++++++------- 2 files changed, 12 insertions(+), 7 deletions(-) create mode 100644 Doc/tools/clean-files.txt diff --git a/Doc/tools/clean-files.txt b/Doc/tools/clean-files.txt new file mode 100644 index 00000000000000..ba14f7af40bf99 --- /dev/null +++ b/Doc/tools/clean-files.txt @@ -0,0 +1,6 @@ + +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 index af480bbf49ab9c..3a0c1d64f73609 100644 --- a/Doc/tools/touch-clean-files.py +++ b/Doc/tools/touch-clean-files.py @@ -6,12 +6,11 @@ from pathlib import Path -CLEAN = [ - "Doc/library/gc.rst", - "Doc/library/sqlite3.rst", - "Doc/whatsnew/3.12.rst", -] +# Input file has blank line between entries to reduce merge conflicts +CLEAN = Path("Doc/tools/clean-files.txt").read_text(encoding="UTF-8").split("\n") + print("Touching:") for filename in CLEAN: - print(filename) - Path(filename).touch() + if filename: + print(filename) + Path(filename).touch() From e1dd7afa95b5846d2cfbe1a3e36b5c6788388e72 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Thu, 30 Mar 2023 10:33:00 +0300 Subject: [PATCH 5/7] Add comments to input file and strip input --- Doc/tools/clean-files.txt | 3 +++ Doc/tools/touch-clean-files.py | 7 ++++++- 2 files changed, 9 insertions(+), 1 deletion(-) diff --git a/Doc/tools/clean-files.txt b/Doc/tools/clean-files.txt index ba14f7af40bf99..ee5b54b52c543b 100644 --- a/Doc/tools/clean-files.txt +++ b/Doc/tools/clean-files.txt @@ -1,3 +1,6 @@ +# 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 to help avoid merge conflicts. Doc/library/gc.rst diff --git a/Doc/tools/touch-clean-files.py b/Doc/tools/touch-clean-files.py index 3a0c1d64f73609..971aeab97bda20 100644 --- a/Doc/tools/touch-clean-files.py +++ b/Doc/tools/touch-clean-files.py @@ -7,7 +7,12 @@ from pathlib import Path # Input file has blank line between entries to reduce merge conflicts -CLEAN = Path("Doc/tools/clean-files.txt").read_text(encoding="UTF-8").split("\n") +with Path("Doc/tools/clean-files.txt").open() as clean_files: + CLEAN = [ + filename.strip() + for filename in clean_files + if filename.strip() and not filename.startswith("#") + ] print("Touching:") for filename in CLEAN: From e60409eeff104b57151399b8fe8d442f573a33c3 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Thu, 30 Mar 2023 11:12:19 +0300 Subject: [PATCH 6/7] Keep them sorted Co-authored-by: C.A.M. Gerlach --- Doc/tools/clean-files.txt | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/tools/clean-files.txt b/Doc/tools/clean-files.txt index ee5b54b52c543b..a6197998f504fa 100644 --- a/Doc/tools/clean-files.txt +++ b/Doc/tools/clean-files.txt @@ -1,6 +1,7 @@ # 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 to help avoid merge conflicts. +# Add blank lines between files and keep them sorted lexicographically +# to help avoid merge conflicts. Doc/library/gc.rst From a802d55716aae2f2220c35f2e45c0435b46f3759 Mon Sep 17 00:00:00 2001 From: Hugo van Kemenade Date: Thu, 30 Mar 2023 16:21:40 +0300 Subject: [PATCH 7/7] Apply suggestions from code review Co-authored-by: C.A.M. Gerlach --- Doc/tools/touch-clean-files.py | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/Doc/tools/touch-clean-files.py b/Doc/tools/touch-clean-files.py index 971aeab97bda20..07f3e509a09fb5 100644 --- a/Doc/tools/touch-clean-files.py +++ b/Doc/tools/touch-clean-files.py @@ -9,13 +9,12 @@ # Input file has blank line between entries to reduce merge conflicts with Path("Doc/tools/clean-files.txt").open() as clean_files: CLEAN = [ - filename.strip() + Path(filename.strip()) for filename in clean_files if filename.strip() and not filename.startswith("#") ] print("Touching:") for filename in CLEAN: - if filename: - print(filename) - Path(filename).touch() + print(filename) + filename.touch()