Repository navigation
PDFs – using GitHub Actions to build them #181
Description
Activity
There's not too much difference between running/hosting on GitHub Actions/Pages and doing it on the docs server. That's the "easy" bit. The harder bit is maintaining the PDF build and fixing the errors.
I started to work on proof of concept in a separate repository, but came to conclusion that the docsbuild-scripts repository is possibly a better candidate for this purpose. It would allow to reuse code connected with building docs and keeping related processes together.
Other than code re-use (you can clone docsbuild-scripts anywhere), what are the other reasons against a separate community-maintained repo? What's needed from docsbuild-scripts? Can you just clone python/cpython and build from there?
- I think one of biggest culprits was that logs from failed builds were previously available only to very limited group of people, having build jobs logs exposed publicly in GitHub Actions it will be easier for community to act upon the failures from the bottom up (see make logs public? docsbuild-scripts#174)
Yes, this is a good point. But a community-maintained repo would also have visible logs.
I think we can investigate alternative PDF builders simultanously (see
Incomplete sentence, what should we see?
Other than code re-use (you can clone docsbuild-scripts anywhere), what are the other reasons against a separate community-maintained repo? What's needed from docsbuild-scripts? Can you just clone python/cpython and build from there?
I was thinking about discoverability. In fact clone should be enough. My opinion wasn't strong, I am as well ok with continuing working in a separate repository (https://github.com/m-aciek/python-docs-offline).
Incomplete sentence, what should we see?
Current blocker for PDF build using rhinotype is python/cpython#140014. I also have a Copilot-authored PoC of a new builder based on ReportLab Toolkit, but didn't yet have time to test it: m-aciek/sphinx#3. (I thought it's a digression, weren't sure if it's worth going into details, but sharing since you've asked.)
Reacted by Petr Viktorin
In September 2025 we've removed PDF downloads of Python documentation.
Two main reasons were maintenance burden and compute resources. I would like to propose a solution addressing the second of those issues.
Building the offline documentation with GitHub Actions and publishing it with GitHub Pages.
I started to work on proof of concept in a separate repository, but came to conclusion that the docsbuild-scripts repository is possibly a better candidate for this purpose. It would allow to reuse code connected with building docs and keeping related processes together.
My vision is following: docs builds scheduled repeatedly on GitHub Actions and pushed as artifacts to GitHub pages site, with directories layout of docs.python.org offline artifacts. We could then link from Downloads page of online docs to the files from the new automation, either at python.github.io/docsbuild-scripts or at a custom domain under python.org set to serve the site.
Regarding the maintenance burden with PDF docs:
What does the community think? If there are no objections, I'd be happy to start working on a PR for docsbuild-scripts.