gh-139588: Docs: fix PDF build

[m-aciek]

Fix PDF build of documentation.

• Introduced optional sphinxcontrib-svg2pdfconverter dependency in Doc Makefile for PDF build.
• Use sphinxcontrib.rsvgconverter from the package for converting of SVG graphics to PDF format.
• Hide GIF graphics (animations) from PDF (LaTeX) build.

Refs. python/docs-community#182.

Test build is available here: https://github.com/m-aciek/python-docs-offline/actions/runs/22771888107. Artifacts include ZIP to download.

For the reference, problematic docs lines:

• cpython/Doc/library/heapq.rst

  Line 348 in 852ec18

  .. figure:: heapq-binary-tree.svg

• cpython/Doc/library/datetime.rst

  Line 157 in d3b6faf

  .. figure:: datetime-inheritance.svg

• cpython/Doc/library/profiling.sampling.rst

  Line 1197 in 37430ca

  .. figure:: tachyon-live-mode-2.gif

• cpython/Doc/library/profiling.sampling.rst

  Line 1220 in 37430ca

  .. figure:: tachyon-live-mode-1.gif

• Issue: make dist-pdf is broken #139588

---

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

[python-cla-bot]

All commit authors signed the Contributor License Agreement.

[hugovk]

This is essentially identical to venv, except instead of the REQUIREMENTS variable it hardcodes requirements-pdf.txt.

Can dist-pdf instead invoke venv and set REQUIREMENTS to requirements-pdf.txt?

[m-aciek]

Hm, it would be a nice simplification, though after the change two different virtualenvs would share the same location, incorrectly recognising existence of each other.

e.g.
(1) make html -> creates new venv (regular), builds html
(2) then make pdf -> it says venv already exists, therefore we don't rebuild the venv and try to build pdf without extra depenendency

[m-aciek]

Oh, sorry, actually I can also set VENVDIR, I will try it tomorrow.

[m-aciek]

Implemented in 9cb3ba4. I kept the venv-pdf target and reverted adding the dependency from dist-pdf to venv-pdf, for consequence with other dist- targets. Though I made venv-pdf reuse existing venv target definition.

[m-aciek]

(test run after changes: https://github.com/m-aciek/python-docs-offline/actions/runs/22770351164)

[hugovk]

Thanks, looks much better!

I'm wondering if we even need two named venvs.

Right now you can do:

(1) make html -> usual html build
(2) then make htmllive -> will also install the extra sphinx-autobuild dependency

Similarly for (3) make check -> installs pre-commit

Can we follow the same pattern?

[m-aciek]

Thank you for catching that! Suggested approach is even more minimal. Implemented in 4b90701. I don't think we need to pin the package version as long as PDF build is not included in CPython's CI (otherwise I'd do it, for reproducible builds).

[adorilson]

Amazing work, @m-aciek. Thank you.

• Hide GIF graphics (animations) from PDF (LaTeX) build.

Is there a technical reason for it? Of course, I know that in PDF, animation is not possible.
But putting the final state of the animate would be a good thing. For instance, I think turtle docs could have animations in the HTML version, but in the PDF (and other static versions), the current static images.

[m-aciek]

Those graphics didn't seem critical for the content. I think though it would make sense to have a single frame as PNG for formats that don't handle animations. 👍