From 3837b1be54f2648ffb390fcd1dab48d7693c3f6d Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 16 May 2025 01:30:18 +0200 Subject: [PATCH 01/21] Build and check EPUB documentation --- .github/workflows/reusable-docs.yml | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 657e0a6bf662f7..38045f2b72becd 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -75,6 +75,13 @@ jobs: --fail-if-regression \ --fail-if-improved \ --fail-if-new-news-nit + - name: 'Build and check EPUB documentation' + continue-on-error: true + run: | + set -Eeuo pipefail + make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --fail-on-warning" epub + pip install epubcheck + epubcheck build/epub # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release doctest: From 276437ba9e596ad790e01379f7589f0e1b36f803 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 16 May 2025 01:36:10 +0200 Subject: [PATCH 02/21] Specify the epub filename --- .github/workflows/reusable-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 38045f2b72becd..a63f09b44af8ec 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -81,7 +81,7 @@ jobs: set -Eeuo pipefail make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --fail-on-warning" epub pip install epubcheck - epubcheck build/epub + epubcheck build/epub/Python.epub # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release doctest: From 50cf4cb8f9ed3a64db5346cb0d1fca13e17912d4 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 16 May 2025 01:44:28 +0200 Subject: [PATCH 03/21] Fix filepath --- .github/workflows/reusable-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index a63f09b44af8ec..ba70937f803b99 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -81,7 +81,7 @@ jobs: set -Eeuo pipefail make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --fail-on-warning" epub pip install epubcheck - epubcheck build/epub/Python.epub + epubcheck Doc/build/epub/Python.epub # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release doctest: From 870bcea07538fb926aed3f34efb1bea99213e776 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Wed, 2 Jul 2025 00:38:38 +0200 Subject: [PATCH 04/21] Add simple EPUB fatals check --- .github/workflows/reusable-docs.yml | 35 +++++++++++++++++++++++------ Doc/tools/check-epub.py | 26 +++++++++++++++++++++ 2 files changed, 54 insertions(+), 7 deletions(-) create mode 100644 Doc/tools/check-epub.py diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index ba70937f803b99..21a250364171b5 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -75,13 +75,6 @@ jobs: --fail-if-regression \ --fail-if-improved \ --fail-if-new-news-nit - - name: 'Build and check EPUB documentation' - continue-on-error: true - run: | - set -Eeuo pipefail - make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --fail-on-warning" epub - pip install epubcheck - epubcheck Doc/build/epub/Python.epub # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release doctest: @@ -109,3 +102,31 @@ jobs: # Use "xvfb-run" since some doctest tests open GUI windows - name: 'Run documentation doctest' run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="--fail-on-warning" doctest + + epubcheck: + name: 'Docs EPUB check' + runs-on: ubuntu-latest + timeout-minutes: 40 + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - uses: actions/cache@v4 + with: + path: ~/.cache/pip + key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }} + restore-keys: | + ubuntu-doc- + - name: 'Install build dependencies' + run: make -C Doc/ PYTHON=../python venv + - name: 'Build and load EPUB checks to file' + continue-on-error: true + run: | + set -Eeuo pipefail + make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --fail-on-warning" epub + pip install epubcheck + epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt + - name: 'Check for FATAL errors in EPUB' + if: github.event_name == 'pull_request' + run: | + python Doc/tools/check-epub.py diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py new file mode 100644 index 00000000000000..bb41f8c52cf808 --- /dev/null +++ b/Doc/tools/check-epub.py @@ -0,0 +1,26 @@ +import sys +from pathlib import Path + + +def main(): + wrong_directory_msg = "Must run this script from the repo root" + if not Path("Doc").exists() or not Path("Doc").is_dir(): + raise RuntimeError(wrong_directory_msg) + + with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: + warnings = f.read().splitlines() + + warnings = [warning.split(" - ") for warning in warnings] + + fatals = [warning for warning in warnings if warning[0] == "FATAL"] + + if fatals: + print("\nError: must not contain fatal errors:\n") + for fatal in fatals: + print(" - ".join(fatal)) + + return len(fatals) + + +if __name__ == "__main__": + sys.exit(main()) From be7e6f6874234d2c69dbc8d7900becf0aa6bfc47 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Wed, 2 Jul 2025 00:43:19 +0200 Subject: [PATCH 05/21] Fix CI --- .github/workflows/reusable-docs.yml | 21 ++++++++++++++------- 1 file changed, 14 insertions(+), 7 deletions(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 21a250364171b5..5d2c55257b7792 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -108,17 +108,24 @@ jobs: runs-on: ubuntu-latest timeout-minutes: 40 steps: - - uses: actions/checkout@v4 + - name: 'Check out latest PR branch commit' + uses: actions/checkout@v4 with: persist-credentials: false - - uses: actions/cache@v4 + ref: >- + ${{ + github.event_name == 'pull_request' + && github.event.pull_request.head.sha + || '' + }} + - name: 'Set up Python' + uses: actions/setup-python@v5 with: - path: ~/.cache/pip - key: ubuntu-doc-${{ hashFiles('Doc/requirements.txt') }} - restore-keys: | - ubuntu-doc- + python-version: '3' + cache: 'pip' + cache-dependency-path: 'Doc/requirements.txt' - name: 'Install build dependencies' - run: make -C Doc/ PYTHON=../python venv + run: make -C Doc/ venv - name: 'Build and load EPUB checks to file' continue-on-error: true run: | From 2d8b0ce58a8126d54539be4a47bc9341f98e1f43 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Wed, 2 Jul 2025 00:47:40 +0200 Subject: [PATCH 06/21] Exclude index and download page from EPUB build (they are not used) --- Doc/conf.py | 1 + 1 file changed, 1 insertion(+) diff --git a/Doc/conf.py b/Doc/conf.py index 467961dd5e2bff..cbc59dc3b7ec6a 100644 --- a/Doc/conf.py +++ b/Doc/conf.py @@ -512,6 +512,7 @@ epub_author = 'Python Documentation Authors' epub_publisher = 'Python Software Foundation' +epub_exclude_files = ('index.xhtml', 'download.xhtml') # index pages are not valid xhtml # https://github.com/sphinx-doc/sphinx/issues/12359 From 733e2c915fca67ef205c995f317a9baeb54fa4ac Mon Sep 17 00:00:00 2001 From: "blurb-it[bot]" <43283697+blurb-it[bot]@users.noreply.github.com> Date: Tue, 1 Jul 2025 23:01:03 +0000 Subject: [PATCH 07/21] =?UTF-8?q?=F0=9F=93=9C=F0=9F=A4=96=20Added=20by=20b?= =?UTF-8?q?lurb=5Fit.?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .../Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst | 1 + 1 file changed, 1 insertion(+) create mode 100644 Misc/NEWS.d/next/Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst diff --git a/Misc/NEWS.d/next/Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst b/Misc/NEWS.d/next/Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst new file mode 100644 index 00000000000000..70f54936c80f55 --- /dev/null +++ b/Misc/NEWS.d/next/Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst @@ -0,0 +1 @@ +We are now checking for fatal errors in EPUB builds in CI. From 4395f5dd5fcd83a833137ea4f5e72a3b381b30cd Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Wed, 2 Jul 2025 01:06:01 +0200 Subject: [PATCH 08/21] Remove superfluous flag in SPHINXOPTS, shorten step name --- .github/workflows/reusable-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 5d2c55257b7792..bef736ee4b21d8 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -104,7 +104,7 @@ jobs: run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="--fail-on-warning" doctest epubcheck: - name: 'Docs EPUB check' + name: 'EPUB check' runs-on: ubuntu-latest timeout-minutes: 40 steps: @@ -130,7 +130,7 @@ jobs: continue-on-error: true run: | set -Eeuo pipefail - make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --fail-on-warning" epub + make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet" epub pip install epubcheck epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt - name: 'Check for FATAL errors in EPUB' From 418ad4df792b3ff3a8b70f02785adbf4d5840a61 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Thu, 10 Jul 2025 00:42:58 +0200 Subject: [PATCH 09/21] Annotate type of main function, refactor for mypy, rename fatal_warnings variable --- Doc/tools/check-epub.py | 16 +++++++--------- 1 file changed, 7 insertions(+), 9 deletions(-) diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py index bb41f8c52cf808..cd05a4355933aa 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -2,24 +2,22 @@ from pathlib import Path -def main(): +def main() -> int: wrong_directory_msg = "Must run this script from the repo root" if not Path("Doc").exists() or not Path("Doc").is_dir(): raise RuntimeError(wrong_directory_msg) with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: - warnings = f.read().splitlines() + warnings = [warning.split(" - ") for warning in f.read().splitlines()] - warnings = [warning.split(" - ") for warning in warnings] + fatal_warnings = [warning for warning in warnings if warning[0] == "FATAL"] - fatals = [warning for warning in warnings if warning[0] == "FATAL"] - - if fatals: + if fatal_warnings: print("\nError: must not contain fatal errors:\n") - for fatal in fatals: - print(" - ".join(fatal)) + for warning in fatal_warnings: + print(" - ".join(warning)) - return len(fatals) + return len(fatal_warnings) if __name__ == "__main__": From b545811d679e0a5916c2e964887b00cee9f2e31f Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Thu, 10 Jul 2025 00:45:24 +0200 Subject: [PATCH 10/21] Merge EPUB check into build-doc job --- .github/workflows/reusable-docs.yml | 46 +++++++---------------------- 1 file changed, 11 insertions(+), 35 deletions(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index bef736ee4b21d8..390685c8956b1d 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -75,6 +75,17 @@ jobs: --fail-if-regression \ --fail-if-improved \ --fail-if-new-news-nit + - name: 'Build EPUB documentation and load EPUB checks to file' + continue-on-error: true + run: | + set -Eeuo pipefail + make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet" epub + pip install epubcheck + epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt + - name: 'Check for FATAL errors in EPUB' + if: github.event_name == 'pull_request' + run: | + python Doc/tools/check-epub.py # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release doctest: @@ -102,38 +113,3 @@ jobs: # Use "xvfb-run" since some doctest tests open GUI windows - name: 'Run documentation doctest' run: xvfb-run make -C Doc/ PYTHON=../python SPHINXERRORHANDLING="--fail-on-warning" doctest - - epubcheck: - name: 'EPUB check' - runs-on: ubuntu-latest - timeout-minutes: 40 - steps: - - name: 'Check out latest PR branch commit' - uses: actions/checkout@v4 - with: - persist-credentials: false - ref: >- - ${{ - github.event_name == 'pull_request' - && github.event.pull_request.head.sha - || '' - }} - - name: 'Set up Python' - uses: actions/setup-python@v5 - with: - python-version: '3' - cache: 'pip' - cache-dependency-path: 'Doc/requirements.txt' - - name: 'Install build dependencies' - run: make -C Doc/ venv - - name: 'Build and load EPUB checks to file' - continue-on-error: true - run: | - set -Eeuo pipefail - make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet" epub - pip install epubcheck - epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt - - name: 'Check for FATAL errors in EPUB' - if: github.event_name == 'pull_request' - run: | - python Doc/tools/check-epub.py From 02a7bcf2417dc78b7256df5df0b83bb1ce877a77 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sun, 13 Jul 2025 23:59:03 +0200 Subject: [PATCH 11/21] Update names of steps --- .github/workflows/reusable-docs.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 390685c8956b1d..ae3db80f87dea7 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -75,14 +75,14 @@ jobs: --fail-if-regression \ --fail-if-improved \ --fail-if-new-news-nit - - name: 'Build EPUB documentation and load EPUB checks to file' + - name: 'Build EPUB documentation' continue-on-error: true run: | set -Eeuo pipefail make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet" epub pip install epubcheck epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt - - name: 'Check for FATAL errors in EPUB' + - name: 'Check for fatal errors in EPUB' if: github.event_name == 'pull_request' run: | python Doc/tools/check-epub.py From 01ba3c6d810996da74a0780332e29b7d53d19252 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:07:53 +0200 Subject: [PATCH 12/21] Temporarily don't fail on EPUB check fatal errors --- .github/workflows/reusable-docs.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index ae3db80f87dea7..0ccdc2b9a53f1a 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -84,6 +84,7 @@ jobs: epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt - name: 'Check for fatal errors in EPUB' if: github.event_name == 'pull_request' + continue-on-error: true # temporarily, until gh-136155 is fixed run: | python Doc/tools/check-epub.py From ea3ed7cfc496a8647105031fc68128b112e63c2c Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:08:29 +0200 Subject: [PATCH 13/21] Wording simplification --- Doc/Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index c8a749a02a89ec..ca7fedc2433936 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -7,8 +7,8 @@ PYTHON = python3 VENVDIR = ./venv UV = uv -SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build -BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb +SPHINXBUILD = env PATH=$(VENVDIR)/bin:$$PATH sphinx-build +BLURB = env PATH=$(VENVDIR)/bin:$$PATH blurb JOBS = auto PAPER = SOURCES = @@ -58,7 +58,7 @@ build: @if [ -f ../Misc/NEWS ] ; then \ echo "Using existing Misc/NEWS file"; \ cp ../Misc/NEWS build/NEWS; \ - elif $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \ + elif which $(BLURB); which $(SPHINXBUILD); $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \ if [ -d ../Misc/NEWS.d ]; then \ echo "Building NEWS from Misc/NEWS.d with blurb"; \ $(BLURB) merge -f build/NEWS; \ From b9c43d70db74c414a4b1081f6c3e484c7260b01b Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:14:40 +0200 Subject: [PATCH 14/21] Rename fatal_errors variable --- Doc/tools/check-epub.py | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py index cd05a4355933aa..4fa2b118e77940 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -10,14 +10,14 @@ def main() -> int: with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: warnings = [warning.split(" - ") for warning in f.read().splitlines()] - fatal_warnings = [warning for warning in warnings if warning[0] == "FATAL"] + fatal_errors = [warning for warning in warnings if warning[0] == "FATAL"] - if fatal_warnings: + if fatal_errors: print("\nError: must not contain fatal errors:\n") - for warning in fatal_warnings: + for warning in fatal_errors: print(" - ".join(warning)) - return len(fatal_warnings) + return len(fatal_errors) if __name__ == "__main__": From 7b41b5e4316c2a792af3fd3fe9c2d28c38761f41 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:16:52 +0200 Subject: [PATCH 15/21] Rename variable used in interation --- Doc/tools/check-epub.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py index 4fa2b118e77940..2a9e70708db662 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -14,8 +14,8 @@ def main() -> int: if fatal_errors: print("\nError: must not contain fatal errors:\n") - for warning in fatal_errors: - print(" - ".join(warning)) + for error in fatal_errors: + print(" - ".join(error)) return len(fatal_errors) From 1f58864f658d5dc20bd481f839e897871be4afec Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:18:50 +0200 Subject: [PATCH 16/21] Remove superfluous variable --- Doc/tools/check-epub.py | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py index 2a9e70708db662..1ba63ef4962267 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -3,9 +3,8 @@ def main() -> int: - wrong_directory_msg = "Must run this script from the repo root" if not Path("Doc").exists() or not Path("Doc").is_dir(): - raise RuntimeError(wrong_directory_msg) + raise RuntimeError("Must run this script from the repo root") with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: warnings = [warning.split(" - ") for warning in f.read().splitlines()] From f043c2e173dcf29394dae785816e92235d4388c2 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:42:10 +0200 Subject: [PATCH 17/21] Wording simplification --- .github/workflows/reusable-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 0ccdc2b9a53f1a..58c1e4391602c9 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -84,7 +84,7 @@ jobs: epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt - name: 'Check for fatal errors in EPUB' if: github.event_name == 'pull_request' - continue-on-error: true # temporarily, until gh-136155 is fixed + continue-on-error: true # until gh-136155 is fixed run: | python Doc/tools/check-epub.py From 45738931c3b446b821d574be3e0248b4826e54e3 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:42:19 +0200 Subject: [PATCH 18/21] Revert "Wording simplification" -- it was another file commited by mistake This reverts commit ea3ed7cfc496a8647105031fc68128b112e63c2c. --- Doc/Makefile | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index ca7fedc2433936..c8a749a02a89ec 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -7,8 +7,8 @@ PYTHON = python3 VENVDIR = ./venv UV = uv -SPHINXBUILD = env PATH=$(VENVDIR)/bin:$$PATH sphinx-build -BLURB = env PATH=$(VENVDIR)/bin:$$PATH blurb +SPHINXBUILD = PATH=$(VENVDIR)/bin:$$PATH sphinx-build +BLURB = PATH=$(VENVDIR)/bin:$$PATH blurb JOBS = auto PAPER = SOURCES = @@ -58,7 +58,7 @@ build: @if [ -f ../Misc/NEWS ] ; then \ echo "Using existing Misc/NEWS file"; \ cp ../Misc/NEWS build/NEWS; \ - elif which $(BLURB); which $(SPHINXBUILD); $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \ + elif $(BLURB) help >/dev/null 2>&1 && $(SPHINXBUILD) --version >/dev/null 2>&1; then \ if [ -d ../Misc/NEWS.d ]; then \ echo "Building NEWS from Misc/NEWS.d with blurb"; \ $(BLURB) merge -f build/NEWS; \ From f2e74c9059d97b105f09caed04712c174e635af3 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Mon, 14 Jul 2025 00:50:45 +0200 Subject: [PATCH 19/21] Remove redundant --fail-on-warning --- .github/workflows/reusable-docs.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 58c1e4391602c9..7b9dc4818577eb 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -66,7 +66,7 @@ jobs: run: | set -Eeuo pipefail # Build docs with the nit-picky option; write warnings to file - make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --fail-on-warning --warning-file sphinx-warnings.txt" html + make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --warning-file sphinx-warnings.txt" html - name: 'Check warnings' if: github.event_name == 'pull_request' run: | From 7a170c138d7e4714aec16af5d915fcc0b0a6ce10 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Tue, 15 Jul 2025 08:54:51 +0200 Subject: [PATCH 20/21] Revert literal in raised exception --- Doc/tools/check-epub.py | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py index 1ba63ef4962267..2a9e70708db662 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -3,8 +3,9 @@ def main() -> int: + wrong_directory_msg = "Must run this script from the repo root" if not Path("Doc").exists() or not Path("Doc").is_dir(): - raise RuntimeError("Must run this script from the repo root") + raise RuntimeError(wrong_directory_msg) with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: warnings = [warning.split(" - ") for warning in f.read().splitlines()] From e5610bb7c6f9b68dc67f8f81c9da941b545f3998 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Tue, 15 Jul 2025 08:55:19 +0200 Subject: [PATCH 21/21] Rename helper variable to message --- Doc/tools/check-epub.py | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py index 2a9e70708db662..693dc239c8ad58 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -8,9 +8,9 @@ def main() -> int: raise RuntimeError(wrong_directory_msg) with Path("Doc/epubcheck.txt").open(encoding="UTF-8") as f: - warnings = [warning.split(" - ") for warning in f.read().splitlines()] + messages = [message.split(" - ") for message in f.read().splitlines()] - fatal_errors = [warning for warning in warnings if warning[0] == "FATAL"] + fatal_errors = [message for message in messages if message[0] == "FATAL"] if fatal_errors: print("\nError: must not contain fatal errors:\n")