gh-136155: Docs: check for EPUB fatal errors in CI by m-aciek · Pull Request #134074 · python/cpython

m-aciek · 2025-05-15T23:36:45Z

Validate EPUB documentation for not having warnings with level FATAL when running EPUBCheck in the CI.

This should prevent issues similar to #136155 in the future.

The check will pass after rebase on #136187 merged to the main branch.

Issue: Docs: EPUB builds are broken #136155

hugovk

Thanks for the PR!

hugovk · 2025-07-07T12:13:41Z

Doc/conf.py


 epub_author = 'Python Documentation Authors'
 epub_publisher = 'Python Software Foundation'
+epub_exclude_files = ('index.xhtml', 'download.xhtml')


For reference:

A sequence of files that are generated/copied in the build directory but should not be included in the EPUB file.
https://www.sphinx-doc.org/en/master/usage/configuration.html#confval-epub_exclude_files

Doc/tools/check-epub.py

.github/workflows/reusable-docs.yml

…ngs variable

hugovk

Thanks, looks good.

We'll need to wait for #136155 (comment) / sphinx-doc/sphinxext-opengraph#136 / sphinx-doc/sphinxext-opengraph#137 to be fixed before merging.

But they're taking some time. Until sphinxext-opengraph is fixed and released, is it useful to log these errors in CI, without failing? Or shall we wait a bit longer?

.github/workflows/reusable-docs.yml

m-aciek · 2025-07-11T16:42:46Z

Would it be worth to add .epubcheckignore listing eight failing files?

hugovk · 2025-07-11T17:05:24Z

As a custom file? Probably not, because it would only be for the short term. Unlike .nitignore, we cannot have any fatal errors or the EPUB is broken.

hugovk · 2025-07-15T12:26:30Z

Thank you!

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

miss-islington-app · 2025-08-08T01:51:12Z

Thanks @m-aciek for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.13.
🐍🍒⛏🤖

miss-islington-app · 2025-08-08T01:51:13Z

Thanks @m-aciek for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.14.
🐍🍒⛏🤖

…4074) (cherry picked from commit 624bf52) Co-authored-by: Maciej Olko <maciej.olko@affirm.com> Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>

bedevere-app · 2025-08-08T01:51:24Z

GH-137538 is a backport of this pull request to the 3.13 branch.

bedevere-app · 2025-08-08T01:51:28Z

GH-137539 is a backport of this pull request to the 3.14 branch.

…#137538) 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>

…#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>

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

…onGH-134074) (python#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>

miss-islington-app · 2026-03-03T13:44:38Z

Thanks @m-aciek for the PR, and @hugovk for merging it 🌮🎉.. I'm working now to backport this PR to: 3.12.
🐍🍒⛏🤖

miss-islington-app · 2026-03-03T13:44:41Z

Sorry, @m-aciek and @hugovk, I could not cleanly backport this to 3.12 due to a conflict.
Please backport using cherry_picker on command line.

cherry_picker 624bf52c83abcb1f948f9059e29729fa94d38086 3.12

hugovk · 2026-03-03T13:46:52Z

Backport needed for (at least) 3.12, because the release scripts are testing the EPUB, and we need epub_exclude_files to exclude download.xhtml and its meta tags: https://github.com/python/release-tools/actions/runs/22623483634/job/65554608270

bedevere-app · 2026-03-03T13:49:34Z

GH-145471 is a backport of this pull request to the 3.12 branch.

…onGH-134074) (cherry picked from commit 624bf52) Co-authored-by: Maciej Olko <maciej.olko@affirm.com> Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>

…#145471) (cherry picked from commit 624bf52) Co-authored-by: Maciej Olko <maciej.olko@affirm.com> Co-authored-by: blurb-it[bot] <43283697+blurb-it[bot]@users.noreply.github.com>

hugovk · 2026-03-03T15:20:15Z

And I think 3.10 and 3.11 should be fine without backports. They do have download.xhtml, but don't have the problematic <meta> tags:

m-aciek added 3 commits May 16, 2025 01:30

Build and check EPUB documentation

3837b1b

Specify the epub filename

276437b

Fix filepath

50cf4cb

m-aciek referenced this pull request in python/python-docs-pl May 16, 2025

Build EPUB, lint it for 3.14

79e1a15

m-aciek added 3 commits July 2, 2025 00:38

Add simple EPUB fatals check

870bcea

Fix CI

be7e6f6

Exclude index and download page from EPUB build (they are not used)

2d8b0ce

m-aciek changed the title ~~Docs EPUB: check in CI~~ Docs EPUB: check fatal errors in CI Jul 1, 2025

📜🤖 Added by blurb_it.

733e2c9

m-aciek changed the title ~~Docs EPUB: check fatal errors in CI~~ gh-136155: Docs: check for EPUB fatal errors in CI Jul 1, 2025

bedevere-app bot mentioned this pull request Jul 1, 2025

Docs: EPUB builds are broken #136155

Closed

m-aciek marked this pull request as ready for review July 1, 2025 23:02

m-aciek requested review from AA-Turner, ezio-melotti and hugovk as code owners July 1, 2025 23:02

bedevere-app bot added the awaiting review label Jul 1, 2025

Remove superfluous flag in SPHINXOPTS, shorten step name

4395f5d

hugovk reviewed Jul 7, 2025

View reviewed changes

m-aciek added 3 commits July 7, 2025 21:53

Merge branch 'main' into ci-epubcheck

f2cd73c

Annotate type of main function, refactor for mypy, rename fatal_warni…

418ad4d

…ngs variable

Merge EPUB check into build-doc job

b545811

hugovk reviewed Jul 11, 2025

View reviewed changes

.github/workflows/reusable-docs.yml Outdated Show resolved Hide resolved

.github/workflows/reusable-docs.yml Outdated Show resolved Hide resolved

m-aciek added 6 commits July 13, 2025 23:59

Update names of steps

02a7bcf

Temporarily don't fail on EPUB check fatal errors

01ba3c6

Wording simplification

ea3ed7c

Rename fatal_errors variable

b9c43d7

Rename variable used in interation

7b41b5e

Remove superfluous variable

1f58864

hugovk merged commit 624bf52 into python:main Jul 15, 2025
41 checks passed

bedevere-app bot removed the awaiting review label Jul 15, 2025

m-aciek deleted the ci-epubcheck branch July 15, 2025 13:28

hugovk mentioned this pull request Aug 3, 2025

GH-136155: Fail the EPUB check on fatal errors #137351

Merged

taegyunkim pushed a commit to taegyunkim/cpython that referenced this pull request Aug 4, 2025

pythongh-136155: Docs: check for EPUB fatal errors in CI (python#134074)

b7bc299

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

AA-Turner added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels Aug 8, 2025

bedevere-app bot removed the needs backport to 3.13 bugs and security fixes label Aug 8, 2025

bedevere-app bot removed the needs backport to 3.14 bugs and security fixes label Aug 8, 2025

Agent-Hellboy pushed a commit to Agent-Hellboy/cpython that referenced this pull request Aug 19, 2025

pythongh-136155: Docs: check for EPUB fatal errors in CI (python#134074)

951561b

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

hugovk added the needs backport to 3.12 only security fixes label Mar 3, 2026

miss-islington-app bot assigned hugovk Mar 3, 2026

bedevere-app bot removed the needs backport to 3.12 only security fixes label Mar 3, 2026

Uh oh!

Conversation

m-aciek commented May 15, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

hugovk Jul 7, 2025

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

hugovk left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

m-aciek commented Jul 11, 2025

Uh oh!

hugovk commented Jul 11, 2025

Uh oh!

Uh oh!

hugovk commented Jul 15, 2025

Uh oh!

miss-islington-app bot commented Aug 8, 2025

Uh oh!

miss-islington-app bot commented Aug 8, 2025

Uh oh!

bedevere-app bot commented Aug 8, 2025

Uh oh!

bedevere-app bot commented Aug 8, 2025

Uh oh!

miss-islington-app bot commented Mar 3, 2026

Uh oh!

miss-islington-app bot commented Mar 3, 2026

Uh oh!

hugovk commented Mar 3, 2026

Uh oh!

bedevere-app bot commented Mar 3, 2026

Uh oh!

hugovk commented Mar 3, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

m-aciek commented May 15, 2025 •

edited

Loading