make dist-pdf is broken

@StanFromIreland

Documentation

make dist-pdf is raising some errors.

The first one that I could find was caused by #133591.

A possible solution is to convert the SVG to PDF and use .. figure:: heapq-binary-tree.*

A question from a @StanFromIreland 's comment:

Why was the LaTeX file used to generate the SVG file not versioned? I think it should be.

Linked PRs

@adorilson

@adorilson please wait until we've agreed the correct solution before opening a PR. Are we entirely sure it fixes any problems with SVGs?

A

I installed Inkscape,
added \usepackage{svg} in 30th line of library.tex,
then replaced \sphinxincludegraphics{{heapq-binary-tree}.svg} with \includesvg{{heapq-binary-tree}.svg},
then invoked latexmk -f --shell-escape -pdf -dvi- -ps- 'library.tex' (--shell-escape is not in Makefile).

PDF rendered just fine.

Feature request in Sphinx: sphinx-doc/sphinx#13953

That sounds like a good solution, thanks for your work on this Maciek!

@mgeier

Jupyter Notebook Tools for Sphinx recommend sphinxcontrib-svg2pdfconverter. This package provides three extensions basing on three different backends. @mgeier recommends rsvg-convert as more lightweight and using less memory than Inkscape one. Also CairoSVG looks promising.

We have quite a few options:

solution	details	pros	cons
sphinxcontrib.cairosvgconverter	Python lib	fast, ~~easy to install (Python) = more portable~~	partial SVG spec coverage
sphinxcontrib.rsvgconverter	librsvg: C lib	fast, broad SVG spec coverage	C lib, operating system dependency
CTAN's svg package	uses Inkscape	most idiomatic (works on LaTeX level); full SVG spec coverage	requires work in Sphinx; Inkscape is slow, dependency-heavy
sphinxcontrib.inkscapeconverter	uses Inkscape	full SVG spec coverage	Inkscape is slow, dependency-heavy
sphinx.ext.imgconverter	uses Inkscape or librsvg	built-in in Sphinx	ImageMagick rasterizes a SVG image on conversion. As a result, the image becomes not scalable.

I think our SVGs should be easy to convert (not using SVG spec's quirks and edge cases), and CairoSVG would be easier to install as a Python library, available on PyPI. ~~Therefore I personally think that the cairosvgconverter is the best option for us.~~ (update: I've changed my mind, opened a PR with the rsvg) CairoSVG is 8.4 MB, we should make it an optional dependency, to install it only for PDF builds.

For what it's worth, Cairo is not as lightweight as I thought:

CairoSVG and its dependencies may require additional tools during the installation: a compiler, Python headers, Cairo, and FFI headers. These tools have different names depending on the OS you are using, but:

on Windows, you’ll have to install Cairo (with GTK for example) and Visual C++ compiler for Python;

on macOS, you’ll have to install cairo and libffi (with Homebrew for example);

on Linux, you’ll have to install the cairo, python3-dev and libffi-dev packages (names may vary for your distribution).

For what it's worth, there's another issue impacting stable 3.14 branch, introduced most probably in 9eee7fe (seen in pl lang CI between 5b64b59 and df739f3 commits), caused presumably by high depth of nesting (six levels) in executionmodel.rst:

cpython/Doc/reference/executionmodel.rst

Lines 474 to 479 in e8e0f41

    
              | **host machine** 
        
              |   **process** (global resources) 
        
              |     Python global runtime (*state*) 
        
              |       Python interpreter (*state*) 
        
              |         **thread** (runs Python bytecode and "C-API") 
        
              |           Python thread *state*

I think that is the cause of ! LaTeX Error: Too deeply nested. in the reference when building the PDF. We can fix it either by setting \setcounter{maxdepth}{6} (?) in the document preamble or by refactoring the docs fragment.

For what it's worth, there's another issue impacting stable 3.14 branch,

This is why I started the issue with "make dist-pdf is raising some errors.".

What's next? :)

For what it's worth, there's

cpython/Doc/reference/executionmodel.rst

Lines 474 to 479 in e8e0f41

| **host machine**

| **process** (global resources)

| Python global runtime (*state*)

| Python interpreter (*state*)

| **thread** (runs Python bytecode and "C-API")

| Python thread *state*

I think that is the cause of ! LaTeX Error: Too deeply nested. in the reference when building the PDF. We can fix it either by setting \setcounter{maxdepth}{6} (?) in the document preamble or by refactoring the docs fragment.

Maybe check 'maxlistdepth' key of https://www.sphinx-doc.org/en/master/latex.html#the-latex-elements-configuration-setting

We have quite a few options:

Maybe you could add sphinx.ext.graphviz. It is Python lib and built-in in Sphinx.
I don't see any obvious cons. Maybe could it be complex?

gh-139588: Increase maximum LaTeX list depth (#140709)

pythongh-139588: Increase maximum LaTeX list depth (pythonGH-140709)

[3.14] gh-139588: Increase maximum LaTeX list depth (GH-140709) (#140724

[3.13] gh-139588: Increase maximum LaTeX list depth (GH-140709) (#140725

Back to the SVG topic. Options update:

solution	details	pros	cons
adding PDF graph to sources	sphinx-doc/sphinx#13953 (comment)	simple, doesn't add docs build-time dependency	adds an extra file to sources
converting graph to graphviz and using `sphinx.ext.graphviz`	#139588 (comment)		adds Graphviz as docs build-time dependency, requires graph code conversion
CTAN's svg package	sphinx-doc/sphinx#13953	works on LaTeX level	requires work in Sphinx; depends on Inkscape, requires --shell-escape in `latexmk` command
sphinx.ext.imgconverter	#139635	built-in in Sphinx	depends on ImageMagick; ImageMagick rasterizes a SVG image on conversion. As a result, the image becomes not scalable.

We rejected sphinxcontrib-svg2pdfconverter dependency addition not to add a new external dependency.

@jfbu

Every solution other than adding PDF to sources require introducing at least one big third-party build-time dependency.

Also @jfbu expressed concerns about bringing CTAN's svg package support into Sphinx.

Another option, not included earlier, would be to pre-generate heapq images from source as a new pre-step for builders, but I think its sophistication is not worth it. It still requires a dependency to convert the PDF to SVG, so it is equivalent to other options requiring dependencies.

That said, I'd appreciate a review on #140926, which is the implementation on in my opinion the best available option.

With #140926 current main branch builds PDFs (with dist-pdf) just fine. It means that we have no more that those two issues (one fixed, one in progress) related to this GitHub ticket.

pythongh-139588: Increase maximum LaTeX list depth (python#140709)

gh-139588: Docs: fix PDF build (#145480)

pythongh-139588: Docs: fix PDF build

[3.14] gh-139588: Docs: fix PDF build (#145741)

As far as I'm concerned with #145480 and #145741 this issue is completed.

pythongh-139588: Docs: fix PDF build (python#145480)

gh-139588: Fix nondeterministic `make latex` doc build under parallel…

[3.15] gh-139588: Fix nondeterministic `make latex` doc build under p…

pythongh-139588: Fix nondeterministic `make latex` doc build under pa…

Navigation Menu

Repository navigation

make dist-pdf is broken #139588

Documentation

Linked PRs

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

	\| host machine
	\| process (global resources)
	\| Python global runtime (state)
	\| Python interpreter (state)
	\| thread (runs Python bytecode and "C-API")
	\| Python thread state

make dist-pdf is broken #139588

Description

Documentation

Linked PRs

Activity

AA-Turner commented on Oct 6, 2025

m-aciek commented on Oct 15, 2025

StanFromIreland commented on Oct 15, 2025

m-aciek commented on Oct 15, 2025

m-aciek commented on Oct 16, 2025

m-aciek commented on Oct 19, 2025

m-aciek commented on Oct 21, 2025

adorilson commented on Oct 21, 2025

jfbu commented on Oct 26, 2025

adorilson commented on Oct 28, 2025

m-aciek commented on Oct 29, 2025

m-aciek commented on Nov 9, 2025

m-aciek commented on Nov 10, 2025

m-aciek commented on Apr 1, 2026

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions