https://github.com/python/cpython/commit/624bf52c83abcb1f948f9059e29729fa94d38086
commit: 624bf52c83abcb1f948f9059e29729fa94d38086
branch: main
author: Maciej Olko <maciej.o...@affirm.com>
committer: hugovk <1324225+hug...@users.noreply.github.com>
date: 2025-07-15T15:26:24+03:00
summary:
gh-136155: Docs: check for EPUB fatal errors in CI (#134074)
Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>
files:
A Doc/tools/check-epub.py
A Misc/NEWS.d/next/Documentation/2025-07-01-23-00-58.gh-issue-136155.4siQQO.rst
M .github/workflows/reusable-docs.yml
M Doc/conf.py
diff --git a/.github/workflows/reusable-docs.yml
b/.github/workflows/reusable-docs.yml
index 657e0a6bf662f7..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: |
@@ -75,6 +75,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 c1ed94d7b46ec2..1c1f36e5bc0737 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -448,6 +448,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
diff --git a/Doc/tools/check-epub.py b/Doc/tools/check-epub.py
new file mode 100644
index 00000000000000..693dc239c8ad58
--- /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
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.
_______________________________________________
Python-checkins mailing list -- python-checkins@python.org
To unsubscribe send an email to python-checkins-le...@python.org
https://mail.python.org/mailman3//lists/python-checkins.python.org
Member address: arch...@mail-archive.com
