From 6c6f52823d173c50595e18250d05c64829b9aec8 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Sun, 19 Oct 2025 23:50:53 +0200 Subject: [PATCH 1/6] 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 Date: Wed, 4 Mar 2026 23:00:08 +0100 Subject: [PATCH 2/6] 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 Date: Wed, 4 Mar 2026 18:25:56 +0100 Subject: [PATCH 3/6] 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. From 83e4b7e812c694c545087102dfab4611fcd07d93 Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 6 Mar 2026 00:05:31 +0100 Subject: [PATCH 4/6] Bump svg2pdfconverter to 2.1.0 --- Doc/requirements-pdf.txt | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Doc/requirements-pdf.txt b/Doc/requirements-pdf.txt index b9713817a6f044..e56abc39980eb8 100644 --- a/Doc/requirements-pdf.txt +++ b/Doc/requirements-pdf.txt @@ -1,3 +1,3 @@ -r requirements.txt -sphinxcontrib-svg2pdfconverter~=2.0.0 +sphinxcontrib-svg2pdfconverter~=2.1.0 From 9cb3ba4dd5d46c85b015699403defcda2457aeaa Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 6 Mar 2026 16:33:19 +0100 Subject: [PATCH 5/6] Reuse existing venv target for PDF venv creation --- Doc/Makefile | 21 ++++----------------- 1 file changed, 4 insertions(+), 17 deletions(-) diff --git a/Doc/Makefile b/Doc/Makefile index 86ca95307651c8..9503983c48f9f9 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -187,22 +187,9 @@ venv: .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 + venv-pdf: REQUIREMENTS = requirements-pdf.txt + venv-pdf: VENVDIR = $(VENVDIR_PDF) + venv-pdf: venv .PHONY: dist-no-html dist-no-html: dist-text dist-epub dist-texinfo @@ -251,7 +238,7 @@ dist-text: @echo "Build finished and archived!" .PHONY: dist-pdf -dist-pdf: venv-pdf +dist-pdf: # archive the A4 latex @echo "Building LaTeX (A4 paper)..." mkdir -p dist From 4b90701adab89bbf16dacea4b740609348bd48ae Mon Sep 17 00:00:00 2001 From: Maciej Olko Date: Fri, 6 Mar 2026 17:15:17 +0100 Subject: [PATCH 6/6] Revert separate environment for PDF build, add _ensure-sphinxcontrib-svg2pdfconverter Makefile target --- Doc/Makefile | 18 ++++++++---------- Doc/conf.py | 2 +- Doc/requirements-pdf.txt | 3 --- 3 files changed, 9 insertions(+), 14 deletions(-) delete mode 100644 Doc/requirements-pdf.txt diff --git a/Doc/Makefile b/Doc/Makefile index 9503983c48f9f9..7bdabd8bf168fe 100644 --- a/Doc/Makefile +++ b/Doc/Makefile @@ -6,7 +6,6 @@ # 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 @@ -89,6 +88,7 @@ htmlhelp: build "build/htmlhelp/pydoc.hhp project file." .PHONY: latex +latex: _ensure-sphinxcontrib-svg2pdfconverter latex: BUILDER = latex latex: build @echo "Build finished; the LaTeX files are in build/latex." @@ -164,7 +164,7 @@ clean: clean-venv .PHONY: clean-venv clean-venv: - rm -rf $(VENVDIR) $(VENVDIR_PDF) + rm -rf $(VENVDIR) .PHONY: venv venv: @@ -185,12 +185,6 @@ venv: echo "The venv has been created in the $(VENVDIR) directory"; \ fi -.PHONY: venv-pdf -venv-pdf: - venv-pdf: REQUIREMENTS = requirements-pdf.txt - venv-pdf: VENVDIR = $(VENVDIR_PDF) - venv-pdf: venv - .PHONY: dist-no-html dist-no-html: dist-text dist-epub dist-texinfo @@ -238,13 +232,13 @@ dist-text: @echo "Build finished and archived!" .PHONY: dist-pdf -dist-pdf: +dist-pdf: _ensure-sphinxcontrib-svg2pdfconverter # 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 VENVDIR=$(VENVDIR_PDF) + $(MAKE) latex PAPER=a4 # 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) @@ -299,6 +293,10 @@ _ensure-pre-commit: _ensure-sphinx-autobuild: $(MAKE) _ensure-package PACKAGE=sphinx-autobuild +.PHONY: _ensure-sphinxcontrib-svg2pdfconverter +_ensure-sphinxcontrib-svg2pdfconverter: + $(MAKE) _ensure-package PACKAGE=sphinxcontrib-svg2pdfconverter + .PHONY: check check: _ensure-pre-commit $(VENVDIR)/bin/python3 -m pre_commit run --all-files diff --git a/Doc/conf.py b/Doc/conf.py index a1991bd71024a7..26497083d28e47 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/*', 'venv-pdf/*', 'README.rst'] +exclude_patterns = ['includes/*.rst', 'venv/*', 'README.rst'] venvdir = os.getenv('VENVDIR') if venvdir is not None: exclude_patterns.append(venvdir + '/*') diff --git a/Doc/requirements-pdf.txt b/Doc/requirements-pdf.txt deleted file mode 100644 index e56abc39980eb8..00000000000000 --- a/Doc/requirements-pdf.txt +++ /dev/null @@ -1,3 +0,0 @@ --r requirements.txt - -sphinxcontrib-svg2pdfconverter~=2.1.0