PDF building support

[m-aciek]

We are in an impasse regarding building the PDF documentation. We didn't declare completely dropping its support [1][2], yet PDF build is broken for 3.15 since October 2025, and recently 3.14 builds started to fail. (I'm opening this ticket hoping to facilitate further discussion.)

In October 2025 first SVG image has been added to documentation without uploading the PDF version of image. python/cpython#133591

Recently a similar change has been backported to 3.14 breaking the 3.14 build. python/cpython#144956

I want to note that those are not first vector images in the repository, and there are already two places in the docs, where we have multiple formats of image preserved for different docs builds:

• turtle star
• C-API object lifecycle (the inclusion syntax is complicated for anchors in the online version of image)

Using image.* wildcard in image directive and storing multiple image formats has precedence in Python docs for long now.

Alternatives

• an alternative would be to use sphinxcontrib-svg2pdfconverter, recommended by Jupyter Tools for Sphinx
  • we could put the requirement in a separate file, not to put it to standard requirements.txt superfluously
• store PDF images in a separate repository (I proposed it on community Discord) – this has a disadvantage of not supporting local builds for users
• we were considering extending Sphinx with "native" support of SVG conversion (through docutils, with unsafe --shell-escape flag), but arguments against that are safety and resources LaTeX: use CTAN's svg package sphinx-doc/sphinx#13953
• converting the images in a pre-build step, not in Sphinx – that complicates the build, requires image converter dependency

Footnotes

[1] devguide says: "The documentation in HTML, PDF or EPUB format is generated from text files written using the reStructuredText format and contained in the CPython Git repository."

[2] Adam T.:

On the question of framing, and ability to render the documentation to PDFs in the future, I feel it is important to note we are not wholesale removing the support we currently have. We will continue to accept patches and PRs to fix broken builds. What changes is that the Python project will no longer provide PDFs as pre-built artefacts. The Developer’s Guide can continue to list the instructions needed to create PDFs locally, and perhaps those instructions could even be improved.

https://discuss.python.org/t/removing-non-html-pdf-epub-etc-documentation-downloads/101343/54