From 6c6f52823d173c50595e18250d05c64829b9aec8 Mon Sep 17 00:00:00 2001
From: Maciej Olko <maciej.olko@affirm.com>
Date: Sun, 19 Oct 2025 23:50:53 +0200
Subject: [PATCH 1/3] Docs: PDF: convert SVG to PDF using
 sphinxcontrib.rsvgconverter

---
 Doc/conf.py              | 1 +
 Doc/requirements-pdf.txt | 3 +++
 2 files changed, 4 insertions(+)
 create mode 100644 Doc/requirements-pdf.txt

diff --git a/Doc/conf.py b/Doc/conf.py
index 545049bb460419..26497083d28e47 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -46,6 +46,7 @@
     'linklint.ext',
     'notfound.extension',
     'sphinxext.opengraph',
+    'sphinxcontrib.rsvgconverter',
 )
 for optional_ext in _OPTIONAL_EXTENSIONS:
     try:
diff --git a/Doc/requirements-pdf.txt b/Doc/requirements-pdf.txt
new file mode 100644
index 00000000000000..b9713817a6f044
--- /dev/null
+++ b/Doc/requirements-pdf.txt
@@ -0,0 +1,3 @@
+-r requirements.txt
+
+sphinxcontrib-svg2pdfconverter~=2.0.0

From 273d2aa4bdb5d61fc077d1f909efa1500bd27a9d Mon Sep 17 00:00:00 2001
From: Maciej Olko <maciej.olko@affirm.com>
Date: Wed, 4 Mar 2026 23:00:08 +0100
Subject: [PATCH 2/3] Add support for PDF virtual environment in Makefile

---
 Doc/Makefile | 26 +++++++++++++++++++++++---
 Doc/conf.py  |  2 +-
 2 files changed, 24 insertions(+), 4 deletions(-)

diff --git a/Doc/Makefile b/Doc/Makefile
index 5b7fdf8ec08ed4..86ca95307651c8 100644
--- a/Doc/Makefile
+++ b/Doc/Makefile
@@ -6,6 +6,7 @@
 # You can set these variables from the command line.
 PYTHON       = python3
 VENVDIR      = ./venv
+VENVDIR_PDF  = ./venv-pdf
 UV           = uv
 SPHINXBUILD  = PATH=$(VENVDIR)/bin:$$PATH sphinx-build
 BLURB        = PATH=$(VENVDIR)/bin:$$PATH blurb
@@ -163,7 +164,7 @@ clean: clean-venv
 
 .PHONY: clean-venv
 clean-venv:
-	rm -rf $(VENVDIR)
+	rm -rf $(VENVDIR) $(VENVDIR_PDF)
 
 .PHONY: venv
 venv:
@@ -184,6 +185,25 @@ venv:
 		echo "The venv has been created in the $(VENVDIR) directory"; \
 	fi
 
+.PHONY: venv-pdf
+venv-pdf:
+	@if [ -d $(VENVDIR_PDF) ] ; then \
+		echo "venv-pdf already exists."; \
+		echo "To recreate it, remove it first with \`make clean-venv'."; \
+	else \
+		set -e; \
+		echo "Creating venv in $(VENVDIR_PDF)"; \
+		if $(UV) --version >/dev/null 2>&1; then \
+			$(UV) venv --python=$(PYTHON) $(VENVDIR_PDF); \
+			VIRTUAL_ENV=$(VENVDIR_PDF) $(UV) pip install -r requirements-pdf.txt; \
+		else \
+			$(PYTHON) -m venv $(VENVDIR_PDF); \
+			$(VENVDIR_PDF)/bin/python3 -m pip install --upgrade pip; \
+			$(VENVDIR_PDF)/bin/python3 -m pip install -r requirements-pdf.txt; \
+		fi; \
+		echo "The venv has been created in the $(VENVDIR_PDF) directory"; \
+	fi
+
 .PHONY: dist-no-html
 dist-no-html: dist-text dist-epub dist-texinfo
 
@@ -231,13 +251,13 @@ dist-text:
 	@echo "Build finished and archived!"
 
 .PHONY: dist-pdf
-dist-pdf:
+dist-pdf: venv-pdf
 	# archive the A4 latex
 	@echo "Building LaTeX (A4 paper)..."
 	mkdir -p dist
 	rm -rf build/latex
 	find dist -name 'python-$(DISTVERSION)-docs-pdf*' -exec rm -rf {} \;
-	$(MAKE) latex PAPER=a4
+	$(MAKE) latex PAPER=a4 VENVDIR=$(VENVDIR_PDF)
 	# remove zip & bz2 dependency on all-pdf,
 	# as otherwise the full latexmk process is run twice.
 	# ($$ is needed to escape the $; https://www.gnu.org/software/make/manual/make.html#Basics-of-Variable-References)
diff --git a/Doc/conf.py b/Doc/conf.py
index 26497083d28e47..a1991bd71024a7 100644
--- a/Doc/conf.py
+++ b/Doc/conf.py
@@ -116,7 +116,7 @@
 # Ignore any .rst files in the includes/ directory;
 # they're embedded in pages but not rendered as individual pages.
 # Ignore any .rst files in the venv/ directory.
-exclude_patterns = ['includes/*.rst', 'venv/*', 'README.rst']
+exclude_patterns = ['includes/*.rst', 'venv/*', 'venv-pdf/*', 'README.rst']
 venvdir = os.getenv('VENVDIR')
 if venvdir is not None:
     exclude_patterns.append(venvdir + '/*')

From f6981c9745093ab18c8e2d51cfd12fe951871013 Mon Sep 17 00:00:00 2001
From: Maciej Olko <maciej.olko@affirm.com>
Date: Wed, 4 Mar 2026 18:25:56 +0100
Subject: [PATCH 3/3] Hide GIFs from PDF builds

---
 Doc/library/profiling.sampling.rst | 20 ++++++++++++--------
 1 file changed, 12 insertions(+), 8 deletions(-)

diff --git a/Doc/library/profiling.sampling.rst b/Doc/library/profiling.sampling.rst
index 078062c08c6020..d2b7d9669ab07e 100644
--- a/Doc/library/profiling.sampling.rst
+++ b/Doc/library/profiling.sampling.rst
@@ -1194,10 +1194,12 @@ data, similar to the ``top`` command for system processes::
    python -m profiling.sampling run --live script.py
    python -m profiling.sampling attach --live 12345
 
-.. figure:: tachyon-live-mode-2.gif
-   :alt: Tachyon live mode showing all threads
-   :align: center
-   :width: 100%
+.. only:: not latex
+
+   .. figure:: tachyon-live-mode-2.gif
+      :alt: Tachyon live mode showing all threads
+      :align: center
+      :width: 100%
 
    Live mode displays real-time profiling statistics, showing combined
    data from multiple threads in a multi-threaded application.
@@ -1217,10 +1219,12 @@ main table, showing instruction-level statistics for the currently selected
 function. This panel displays which bytecode instructions are executing most
 frequently, including specialized variants and their base opcodes.
 
-.. figure:: tachyon-live-mode-1.gif
-   :alt: Tachyon live mode with opcode panel
-   :align: center
-   :width: 100%
+.. only:: not latex
+
+   .. figure:: tachyon-live-mode-1.gif
+      :alt: Tachyon live mode with opcode panel
+      :align: center
+      :width: 100%
 
    Live mode with ``--opcodes`` enabled shows an opcode panel with a bytecode
    instruction breakdown for the selected function.