From 49de8fa97bc0d1a5ad8923f52c16380c75126789 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 3 Aug 2025 19:43:19 +0100 Subject: [PATCH 1/4] Fail the EPUB check on fatal errors --- .github/workflows/reusable-docs.yml | 38 ++++++++++++++++++++--------- Doc/tools/check-epub.py | 36 +++++++++++++++------------ 2 files changed, 47 insertions(+), 27 deletions(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 7b9dc4818577eb..3aec64ed192017 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -75,18 +75,6 @@ jobs: --fail-if-regression \ --fail-if-improved \ --fail-if-new-news-nit - - 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' - if: github.event_name == 'pull_request' - continue-on-error: true # until gh-136155 is fixed - run: | - python Doc/tools/check-epub.py # Run "doctest" on HEAD as new syntax doesn't exist in the latest stable release doctest: @@ -114,3 +102,29 @@ 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 + + check-epub: + name: 'Check EPUB' + runs-on: ubuntu-latest + timeout-minutes: 30 + steps: + - uses: actions/checkout@v4 + with: + persist-credentials: false + - 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 + python -m pip install epubcheck + - name: 'Build EPUB documentation' + run: make -C Doc/ PYTHON=../python epub + - name: 'Run epubcheck' + run: 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 index 693dc239c8ad58..6a10096c117542 100644 --- a/Doc/tools/check-epub.py +++ b/Doc/tools/check-epub.py @@ -1,24 +1,30 @@ -import sys from pathlib import Path +CPYTHON_ROOT = Path( + __file__, # cpython/Doc/tools/check-epub.py + '..', # cpython/Doc/tools + '..', # cpython/Doc + '..', # cpython +).resolve() +EPUBCHECK_PATH = CPYTHON_ROOT / 'Doc' / 'epubcheck.txt' -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: - messages = [message.split(" - ") for message in f.read().splitlines()] - fatal_errors = [message for message in messages if message[0] == "FATAL"] +def main() -> int: + lines = EPUBCHECK_PATH.read_text(encoding='utf-8').splitlines() + fatal_errors = [line for line in lines if line.startswith('FATAL')] if fatal_errors: - print("\nError: must not contain fatal errors:\n") - for error in fatal_errors: - print(" - ".join(error)) + err_count = len(fatal_errors) + s = 's' * (err_count != 1) + print() + print(f'Error: epubcheck reported {err_count} fatal error{s}:') + print() + print('\n'.join(fatal_errors)) + return 1 - return len(fatal_errors) + print('Success: no fatal errors found.') + return 0 -if __name__ == "__main__": - sys.exit(main()) +if __name__ == '__main__': + raise SystemExit(main()) From b339b4b430186d3e42162d2caf8874f2b89bbf49 Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+AA-Turner@users.noreply.github.com> Date: Sun, 3 Aug 2025 19:56:24 +0100 Subject: [PATCH 2/4] Update .github/workflows/reusable-docs.yml --- .github/workflows/reusable-docs.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml index 3aec64ed192017..55df9508102f20 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -126,5 +126,4 @@ jobs: - name: 'Run epubcheck' run: 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 c7f7ae6b42357300098526a0d5af2ea2ceeec63f Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 3 Aug 2025 20:25:28 +0100 Subject: [PATCH 3/4] continue-on-error --- .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 55df9508102f20..4473235657ce14 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -124,6 +124,7 @@ jobs: - name: 'Build EPUB documentation' run: make -C Doc/ PYTHON=../python epub - name: 'Run epubcheck' + continue-on-error: true run: epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt - name: 'Check for fatal errors in EPUB' run: python Doc/tools/check-epub.py From 8d42d13d53000d80e6a30d60df405a67e2da47bc Mon Sep 17 00:00:00 2001 From: Adam Turner <9087854+aa-turner@users.noreply.github.com> Date: Sun, 3 Aug 2025 20:26:38 +0100 Subject: [PATCH 4/4] cat Doc/epubcheck.txt --- .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 4473235657ce14..65154aae4c41d5 100644 --- a/.github/workflows/reusable-docs.yml +++ b/.github/workflows/reusable-docs.yml @@ -126,5 +126,6 @@ jobs: - name: 'Run epubcheck' continue-on-error: true run: epubcheck Doc/build/epub/Python.epub &> Doc/epubcheck.txt + - run: cat Doc/epubcheck.txt - name: 'Check for fatal errors in EPUB' run: python Doc/tools/check-epub.py