Skip to content

Docs: remove link elements in builders other than HTML #133720

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Open
wants to merge 2 commits into
base: main
Choose a base branch
from
Open

Docs: remove link elements in builders other than HTML #133720

wants to merge 2 commits into from
+4 −4

Conversation

m-aciek
Copy link
Contributor

@m-aciek m-aciek commented May 8, 2025 •
edited
Loading

Follow-up for #132220 (#132220 (comment)). This change fixes EPUB builds. epubcheck after this change results in 25 fewer errors. Could we please backport it for supported versions?

Before:

% uvx epubcheck 2>&1 >/dev/null | grep 'FATAL'
FATAL - RSC-016 - Python.epub/about.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/bugs.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/abstract.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/allocation.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/apiabiversion.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/arg.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/bool.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/buffer.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/bytearray.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/bytes.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/call.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/capsule.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/cell.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/code.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/codec.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/complex.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/concrete.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/c-api/contextvars.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/contents.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/copyright.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/download.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/glossary.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/index.xhtml:26:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/license.xhtml:27:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
FATAL - RSC-016 - Python.epub/py-modindex.xhtml:29:5 - Fatal Error while parsing file: The element type "link" must be terminated by the matching end-tag "</link>".
Zrzut ekranu 2025-05-9 o 01 11 57

After:

Zrzut ekranu 2025-05-9 o 03 34 10

📚 Documentation preview 📚: https://cpython-previews--133720.org.readthedocs.build/

@m-aciek m-aciek requested review from AA-Turner and hugovk as code owners May 8, 2025 23:11
@m-aciek m-aciek mentioned this pull request May 8, 2025
Merged
@merwok merwok added needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes labels May 9, 2025
@merwok

This comment was marked as outdated.

Sign in to view
@hugovk
Copy link
Member

hugovk commented May 12, 2025

We have three conditionals in a row (extra whitespace for clarity):

    {% if builder == "html" and enable_analytics %}
      <script defer data-domain="docs.python.org" src="https://analytics.python.org/js/script.outbound-links.js"></script>
    {% endif %}
 
   {% if builder == "html" %}<link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html">{% endif %}
 
   {% if builder != "htmlhelp" %}
      {% if pagename == 'whatsnew/changelog' and not embedded %}
      <script type="text/javascript" src="{{ pathto('_static/changelog_search.js', 1) }}"></script>{% endif %}
    {% endif %}

Should that last if builder != "htmlhelp" also be if builder == "html"?

If so, shall we factor that check out? Something along the lines of:

    {% if builder == "html" %}

      {% if enable_analytics %}
        <script defer data-domain="docs.python.org" src="https://analytics.python.org/js/script.outbound-links.js"></script>
      {% endif %}

      <link rel="canonical" href="https://docs.python.org/3/{{pagename}}.html">
 
      {% if pagename == 'whatsnew/changelog' and not embedded %}
      <script type="text/javascript" src="{{ pathto('_static/changelog_search.js', 1) }}"></script>{% endif %}

    {% endif %}

@merwok
Copy link
Member

merwok commented May 13, 2025

@Yhg1s this fixes a bug in docs epub build; would it be acceptable for backport to 3.12 ?

@Yhg1s
Copy link
Member

Yhg1s commented May 13, 2025

Yeah, backporting to 3.12 is fine.

@merwok merwok added the needs backport to 3.12 only security fixes label May 13, 2025
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Reviewers

@merwok merwok merwok approved these changes

@hugovk hugovk hugovk approved these changes

@AA-Turner AA-Turner Awaiting requested review from AA-Turner AA-Turner is a code owner

Assignees
No one assigned
Labels
awaiting merge needs backport to 3.12 only security fixes needs backport to 3.13 bugs and security fixes needs backport to 3.14 bugs and security fixes skip issue skip news
Projects
None yet
Milestone
No milestone
Development

Successfully merging this pull request may close these issues.
5 participants
@m-aciek @merwok @hugovk @Yhg1s @ZeroIntensity