Update .readthedocs.yaml to generate pdfs and epubs #40330
Merged
Conversation
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
So degenerates like me can read on a remarkable Signed-off-by: Joshua Ferguson <joshua.ferguson.273@gmail.com>
qmonnet
reviewed
Jul 2, 2025
There was a problem hiding this comment.
I think we might have got PDFs and/or epubs generated at some point in the past, but I don't remember for sure. @joestringer do you remember? Maybe I'm just getting confused with the epub/latex targets from the docs' Makefile.
@skewballfox How do the options work, where do you download the PDF and epub from once they are generated? And do you know whether there's a way to get a preview these formats before we merge the PR?
|
@qmonnet one of our earliest docs contributors had something like that working at one point, but I'm not at all familiar with it. Personally I only build and consume the HTML version. |
|
As for where the generated documents are available, https://docs.readthedocs.com/platform/stable/downloadable-documentation.html#accessing-offline-formats says:
Regarding the previews, I don't think we get any, given that we build previews with Netlify and not readthedocs. I'm also using exclusively the HTML version (or directly the RST at time), but I don't have any objection to the change. My main concern is what happens if PDF/ePub generation break, I wouldn't like it to prevent the deployment of the HTML version. I'm OK to merge if we keep an eye on the builds - @joestringer, I don't have credentials anymore to access the project on readthedocs so I'm counting on you 😇 (do you know whether it's possible to add more people to the RTD project, by the way?) |
qmonnet
approved these changes
Jul 4, 2025
There was a problem hiding this comment.
Related doc is https://docs.readthedocs.com/platform/stable/config-file/v2.html#formats
It confirms that the formats to list are those to build in addition to HTML, so the PR looks good.
Thanks!
|
/test |
|
The RTD build failed: |
|
I'll try to look into the error message sometime tonight or this morning. |
|
Joe, could you check whether the HTML is still published in this case? Or does the failure to build the PDF halt the deployment? Another question: As far as I remember we don't get notifications when publishing, do we? (The reason I'm asking is that if a failure for PDF/ePub breaks the HTML build and we don't get notified, I'm not sure it's worth it supporting PDF/ePub builds at the risk of silently breaking docs updates. No issue if the HTML version is pushed anyway, though.) |
|
Oh I'm just seeing your message on Slack, and the revert now. That answers my question, thanks for taking care of this! |
|
@qmonnet I'm pretty sure it disrupts the deployment even for HTML: There's probably a way to notify on failures, and yes I think that would be beneficial to set up one way or another. I noticed this time because I was preparing a release candidate which necessitates reconfiguring RTD. Typically I think @cilium/maintainers do this about once a month so there shouldn't be an extended period where we miss a breakage. The repercussion would just be that new updates to the docs won't be published since the last failure - not the worst, but also not ideal. |
|
I didn't realize this would break your CI pipeline. My apologies. when I run this locally it seems to work without failure, maybe I have something installed locally that is a extra system dependency? cd Documentation
# install uv if it's not on your system
# curl -LsSf https://astral.sh/uv/install.sh | sh
uv venv --python 3.11 .venv; and uv pip install pip setuptools; and uv pip install sphinx; and uv pip install -r requirements.txt
uv run python -m sphinx -T -b dirhtml -d _build/doctrees -D language=en . .output/html
uv run python -m sphinx -T -b latex -d _build/doctrees -D language=en . .output/pdfEDIT: |
|
No worries about the CI pipeline breakage, it was an easy fix. Unfortunately it just meant that we had to revert this PR. I agree it's probably just some dependency that's not encoded in |
|
Claude says:
(Other suggestions include using Inkscape as a SVG processor as part of the workflow, looking at ImageMagick policy configuration (unlikely the cause here), using alternative image formats, or skipping image conversion altogether. None of these seem very convenient here.) |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
I'm not sure the below applies to this PR since it's a just exposing an extra option for read the docs
Please ensure your pull request adheres to the following guidelines:
description and a
Fixes: #XXXline if the commit addresses a particularGitHub issue.
Fixes: <commit-id>tag, thenplease add the commit author[s] as reviewer[s] to this issue.
Fixes: #issue-number