Skip to content

Docs: EPUB builds are broken #136155

Closed
Closed
Docs: EPUB builds are broken#136155
Labels
3.11only security fixesdocsDocumentation in the Doc dirtriagedThe issue has been accepted as valid by a triager.

Description

@m-aciek
m-aciek
opened on Jun 30, 2025

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.

Image

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

Activity

  1. m-aciek
    added
    docsDocumentation in the Doc dir
    on Jun 30, 2025
  2. github-project-automation
    added this to docs issueson Jun 30, 2025
  3. github-project-automation
    moved this to Todo in docs issueson Jun 30, 2025
  4. brianschubert
    added
    triagedThe issue has been accepted as valid by a triager.
    on Jun 30, 2025

  5. hugovk commented on Jul 1, 2025

    @hugovk
    hugovk
    on Jul 1, 2025
    Member

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

    Otherwise, let's do #134071.

  6. m-aciek
    added a commit that references this issue on Jul 1, 2025

    pythongh-136155: Docs: don't add custom OpenGraph protocol meta tags …

    716eece

  7. m-aciek commented on Jul 1, 2025

    @m-aciek
    m-aciek
    on Jul 1, 2025
    ContributorAuthor

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

  8. hugovk
    added a commit that references this issue on Jul 7, 2025

    gh-136155: Docs: only add custom OpenGraph protocol meta tags for HTM…

    c45da6a
  9. miss-islington
    added 2 commits that reference this issue on Jul 7, 2025

    pythongh-136155: Docs: only add custom OpenGraph protocol meta tags f…

    65ff40f

    pythongh-136155: Docs: only add custom OpenGraph protocol meta tags f…

    ec2256a

  10. hugovk commented on Jul 8, 2025

    @hugovk
    hugovk
    on Jul 8, 2025
    Member

    #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.)

  11. hugovk
    added 3 commits that reference this issue on Jul 8, 2025

    [3.14] gh-136155: Docs: only add custom OpenGraph protocol meta tags …

    3296d9b

    [3.13] gh-136155: Docs: only add custom OpenGraph protocol meta tags …

    f17be28

    [3.12] pythongh-136155: Docs: only add custom OpenGraph protocol meta…

    c9ab6d3
  12. AndPuQing
    added a commit that references this issue on Jul 11, 2025

    pythongh-136155: Docs: only add custom OpenGraph protocol meta tags f…

    93b9ae0

  13. 39 remaining items

  14. hugovk
    added a commit that references this issue on Sep 10, 2025

    [3.12] pythonGH-136155: Use ``sphinxext-opengraph`` v0.12.0 (pythonGH…

    2239242

  15. hugovk commented on Sep 10, 2025

    @hugovk
    hugovk
    on Sep 10, 2025
    Member

    There's still a problem with the 3.12 EPUB: #136406 (comment)

    Here's an extra backport to fix it: #138741

  16. m-aciek
    reopened this on Sep 10, 2025
  17. hugovk
    added a commit that references this issue on Sep 24, 2025

    [3.12] GH-136155: Use ``sphinxext-opengraph`` v0.12.0 (GH-137393) (#1…

    71c84fa

  18. m-aciek commented on Sep 25, 2025

    @m-aciek
    m-aciek
    on Sep 25, 2025
    ContributorAuthor

    With 3.12 fixed, let's close

  19. m-aciek
    closed this as completedon Sep 25, 2025

  20. hugovk commented on Sep 30, 2025

    @hugovk
    hugovk
    on Sep 30, 2025
    Member

    Do we also need to fix the other security branches: 3.9-3.11?

  21. AA-Turner commented on Sep 30, 2025

    @AA-Turner
    AA-Turner
    on Sep 30, 2025
    Member

    #132220 wasn't backported that far, so there shouldn't've been any changes on our side, it would only be if a bad opengraph version is still there.

  22. hugovk commented on Sep 30, 2025

    @hugovk
    hugovk
    on Sep 30, 2025
    Member

    https://docs.python.org/3.11/download.html still has a bad EPUB: https://docs.python.org/3.11/archives/python-3.11.13-docs.epub

    3.9 and 3.10 are good.

  23. AA-Turner
    reopened this on Sep 30, 2025
  24. StanFromIreland
    added
    3.11only security fixes
    on Sep 30, 2025

  25. hugovk commented on Oct 23, 2025

    @hugovk
    hugovk
    on Oct 23, 2025
    Member

    Looking good now, I checked 3.9, 3.11 and 3.14 🚀

  26. hugovk
    closed this as completedon Oct 23, 2025
  27. hugovk
    added a commit that references this issue on Mar 3, 2026

    [3.12] pythongh-136155: Docs: check for EPUB fatal errors in CI (pyth…

    91ea69c
  28. Yhg1s
    added a commit that references this issue on Mar 3, 2026

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

    ac82ec4
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    3.11only security fixesdocsDocumentation in the Doc dirtriagedThe issue has been accepted as valid by a triager.

    Projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions