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.

m-aciek · 2025-07-13T22:41:29Z

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?

I modified the PR for the case it would be useful.

PS on a shelf I have a changeset to print also regular errors informationally, but I think I will wait with it until fatal errors are gone. EPUB build on my machine produces 92 errors currently and I don't want to make fatal errors to be drown out by them in the logs.

…stake This reverts commit ea3ed7c.

m-aciek · 2025-07-13T22:54:19Z

.github/workflows/reusable-docs.yml

        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


The redundancy can be seen in a job logs (from before the change): https://github.com/python/cpython/actions/runs/16254225968/job/45888071303

Doc/tools/check-epub.py

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>

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

m-aciek added 3 commits July 14, 2025 00:42

Wording simplification

f043c2e

Revert "Wording simplification" -- it was another file commited by mi…

4573893

…stake This reverts commit ea3ed7c.

Remove redundant --fail-on-warning

f2e74c9

m-aciek commented Jul 13, 2025

View reviewed changes

hugovk reviewed Jul 14, 2025

View reviewed changes

Doc/tools/check-epub.py Outdated Show resolved Hide resolved

Doc/tools/check-epub.py Outdated Show resolved Hide resolved

m-aciek added 2 commits July 15, 2025 08:54

Revert literal in raised exception

7a170c1

Rename helper variable to message

e5610bb

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>

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!

m-aciek commented Jul 13, 2025

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

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!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

m-aciek commented May 15, 2025 •

edited

Loading

m-aciek Jul 13, 2025 •

edited

Loading