Skip to content

gh-139588: Docs: PDF: dedicated venv and converting SVG to PDF using sphinxcontrib.rsvgconverter #145480

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Draft
m-aciek wants to merge 10 commits into
base: main
Choose a base branch
from
+30 −5
Draft

gh-139588: Docs: PDF: dedicated venv and converting SVG to PDF using sphinxcontrib.rsvgconverter #145480

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
10 commits
Select commit Hold shift + click to select a range
72c745e
Docs: PDF: convert SVG to PDF using sphinxcontrib.rsvgconverter
m-aciek Oct 19, 2025
571565e
Move new dependency to a new requirements file, upgrade to 2.0.0
m-aciek Feb 28, 2026
6e2f6ef
Initial plan
Copilot Feb 28, 2026
0baf0c7
Doc/Makefile: use separate venv-pdf for dist-pdf target
Copilot Feb 28, 2026
5f78158
Exclude venv-pdf for Sphinx
m-aciek Mar 1, 2026
1e2be87
Exclude venv-pdf for Sphinx, fix
m-aciek Mar 1, 2026
9b21c4d
ignore make latex errors
m-aciek Mar 3, 2026
6730d89
Fix Makefile: correct command syntax for building PDF and zipping output
m-aciek Mar 3, 2026
8255901
Fix Makefile: add --keep-going option to ensure continued processing …
m-aciek Mar 3, 2026
a930739
Fix conf.py: relax depth limit for table of contents in LaTeX output
m-aciek Mar 3, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
28 changes: 24 additions & 4 deletions Doc/Makefile
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -162,7 +163,7 @@ clean: clean-venv

.PHONY: clean-venv
clean-venv:
rm -rf $(VENVDIR)
rm -rf $(VENVDIR) $(VENVDIR_PDF)

.PHONY: venv
venv:
Expand All @@ -183,6 +184,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

Expand Down Expand Up @@ -230,18 +250,18 @@ 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)
-sed -i 's/: all-$$(FMT)/:/' build/latex/Makefile
(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync LATEXMKOPTS='-quiet' all-pdf && $(MAKE) FMT=pdf zip bz2)
(cd build/latex; $(MAKE) clean && $(MAKE) --jobs=$$((`nproc`+1)) --output-sync --keep-going LATEXMKOPTS='-quiet' all-pdf; $(MAKE) FMT=pdf zip bz2)
cp build/latex/docs-pdf.zip dist/python-$(DISTVERSION)-docs-pdf-a4.zip
cp build/latex/docs-pdf.tar.bz2 dist/python-$(DISTVERSION)-docs-pdf-a4.tar.bz2
@echo "Build finished and archived!"
Expand Down
4 changes: 3 additions & 1 deletion Doc/conf.py
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -44,6 +44,7 @@
_OPTIONAL_EXTENSIONS = (
'notfound.extension',
'sphinxext.opengraph',
'sphinxcontrib.rsvgconverter',
)
for optional_ext in _OPTIONAL_EXTENSIONS:
try:
Expand Down Expand Up @@ -113,7 +114,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 + '/*')
Expand Down Expand Up @@ -354,6 +355,7 @@
\let\Verbatim=\OriginalVerbatim
\let\endVerbatim=\endOriginalVerbatim
\setcounter{tocdepth}{2}
\makeatletter\let\@toodeep\relax\makeatother
''',
# The paper size ('letterpaper' or 'a4paper').
'papersize': 'a4paper',
Expand Down
3 changes: 3 additions & 0 deletions Doc/requirements-pdf.txt
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,3 @@
-r requirements.txt

sphinxcontrib-svg2pdfconverter~=2.0.0