[3.14] gh-136155: Docs: check for EPUB fatal errors in CI (GH-134074) (#137539)

Co-authored-by: Maciej Olko <maciej.olko@affirm.com>
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
Co-authored-by: Adam Turner <9087854+AA-Turner@users.noreply.github.com>

.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: |
@@ -102,3 +102,30 @@ 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'
+      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

Doc/conf.py

@@ -448,6 +448,7 @@ latex_appendices = ['glossary', 'about', 'license', 'copyright']
 
 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

Doc/tools/check-epub.py

@@ -0,0 +1,30 @@
+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:
+    lines = EPUBCHECK_PATH.read_text(encoding='utf-8').splitlines()
+    fatal_errors = [line for line in lines if line.startswith('FATAL')]
+
+    if fatal_errors:
+        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
+
+    print('Success: no fatal errors found.')
+    return 0
+
+
+if __name__ == '__main__':
+    raise SystemExit(main())

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.