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

(cherry picked from commit 624bf52c83abcb1f948f9059e29729fa94d38086)

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

diff --git a/.github/workflows/reusable-docs.yml b/.github/workflows/reusable-docs.yml
index 0542092ea286de078b58f908b717430718d7ae20..8b4d96ba48ecf145e48653563c3191add002beea 100644 (file)
--- a/.github/workflows/reusable-docs.yml
+++ b/.github/workflows/reusable-docs.yml
@@ -63,7 +63,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 --keep-going --warning-file sphinx-warnings.txt" html
+        make -C Doc/ PYTHON=../python SPHINXOPTS="--quiet --nitpicky --keep-going --warning-file sphinx-warnings.txt" html
     - name: 'Check warnings'
       if: github.event_name == 'pull_request'
       run: |
@@ -72,6 +72,18 @@ 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:

diff --git a/Doc/conf.py b/Doc/conf.py
index 9cb184d0786029afeb0e80cae5c7f8f43051d95d..23932ff37202419badf4bc06c7f367e7bd2fab63 100644 (file)
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -485,6 +485,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

diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py
new file mode 100644 (file)
index 0000000..693dc23
--- /dev/null
+++ b/Doc/tools/check-epub.py
@@ -0,0 +1,24 @@
+import sys
+from pathlib import Path
+
+
+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"]
+
+    if fatal_errors:
+        print("\nError: must not contain fatal errors:\n")
+        for error in fatal_errors:
+            print(" - ".join(error))
+
+    return len(fatal_errors)
+
+
+if __name__ == "__main__":
+    sys.exit(main())

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 (file)
index 0000000..70f5493
--- /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.