gh-136155: Docs: check for EPUB fatal errors in CI

.github/workflows/reusable-docs.yml

@@ -102,3 +102,38 @@ 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

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

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())

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.