Docs: EPUB builds are broken

[m-aciek]

Documentation

#132220 has broken EPUB builds of documentation. This has been only partially fixed in #133720, because yet configuration of sphinxext-opengraph adds not closed tags to every page.

sphinx-doc/sphinxext-opengraph#136 and sphinx-doc/sphinxext-opengraph#137 have been opened upstream, but the PR is not merged.

Status update [2025-07-14]: now (after skipping OpenGraph custom tags in Docs conf.py) only 8 chapters fail to render in EPUB format. It can be addressed by any of sphinx-doc/sphinxext-opengraph#120 and sphinx-doc/sphinxext-opengraph#137, as far as I'm concerned. Adding a CI check definitely should help with the stability of EPUB build. Last year Inada made an effort to fix the EPUB (#118689).

Linked PRs

• gh-136155: Docs: only add custom OpenGraph protocol meta tags for HTML builds #136187
• gh-136155: Docs: check for EPUB fatal errors in CI #134074
• [3.14] gh-136155: Docs: only add custom OpenGraph protocol meta tags for HTML builds (GH-136187) #136382
• [3.13] gh-136155: Docs: only add custom OpenGraph protocol meta tags for HTML builds (GH-136187) #136383
• [3.12] gh-136155: Use sphinxext-opengraph v0.12.0 #136406
• GH-136155: Use sphinxext-opengraph v0.11.0 #137348
• [3.14] GH-136155: Use sphinxext-opengraph v0.11.0 (GH-137348) #137349
• [3.13] GH-136155: Use sphinxext-opengraph v0.11.0 (GH-137348) #137350
• GH-136155: Fail the EPUB check on fatal errors #137351
• GH-136155: Use sphinxext-opengraph v0.12.0 #137393
• [3.14] GH-136155: Use sphinxext-opengraph v0.12.0 (GH-137393) #137431
• [3.13] GH-136155: Use sphinxext-opengraph v0.12.0 (GH-137393) #137432
• [3.13] gh-136155: Docs: check for EPUB fatal errors in CI (GH-134074) #137538
• [3.14] gh-136155: Docs: check for EPUB fatal errors in CI (GH-134074) #137539
• [3.12] GH-136155: Use sphinxext-opengraph v0.12.0 (GH-137393) #138741
• [3.12] gh-136155: Docs: check for EPUB fatal errors in CI (GH-134074) #145471

[hugovk]

Would you like to open a PR with your tags suggestion from #134071 (comment)?

Otherwise, let's do #134071.

[m-aciek]

I've figured out the tags approach and confirmed it works locally: #136187.

[hugovk]

#136187 has improved it but not fixed them all: #136187 (comment)

They are:

FATAL - RSC-016 - Python.epub/howto/descriptor.xhtml:11:78 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/howto/logging-cookbook.xhtml:11:62 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/howto/logging.xhtml:11:62 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/howto/regex.xhtml:11:64 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/whatsnew/3.4.xhtml:11:66 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/whatsnew/3.5.xhtml:11:71 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/whatsnew/3.6.xhtml:11:71 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.
FATAL - RSC-016 - Python.epub/whatsnew/3.7.xhtml:11:70 - Fatal Error while parsing file: The value of attribute "content" associated with an element type "meta" must not contain the '<' character.

Here's the first couple, the rest are also all similar email address tags:

<meta property="og:description" content="Author, Raymond Hettinger,, Contact,<python at rcn dot com>,. Contents: Descriptor Guide- Primer- Simple example: A descriptor that returns a constant, Dynamic lookups, Managed attributes, Customiz..." />

<meta property="og:description" content="Author, Vinay Sajip <vinay_sajip at red-dove dot com>,. This page contains a number of recipes related to logging, which have been found useful in the past. For links to tutorial and reference info..." />

(macOS tip: opening the EPUB in BBEdit gives a folder-based UI and you can see the plaintext xhtml files inside.)