LaTeX: use CTAN's svg package

[m-aciek]

Is your feature request related to a problem? Please describe.
Currently the documentation fails to build the PDF while trying to include an SVG image.

Describe the solution you'd like
LaTeXTranslator could recognise an SVG and use svg package with \includesvg directive to convert the image in an automated fashion.

Describe alternatives you've considered
sphinx.ext.imgconverter (python/cpython#139635)

Additional context
Using svg package requires using --shell-escape flag in latexmk call. Also it requires a new runtime dependency – Inkscape.

• make dist-pdf is broken python/cpython#139588

[mgeier]

For reference, I have documented the ways that I know how to use SVG images in LaTeX output here: https://nbsphinx.readthedocs.io/en/0.9.7/markdown-cells.html#SVG-support-for-LaTeX

For most use cases, I don't recommend using sphinx.ext.imgconverter, because this turns your SVGs into bitmap images.

I would recommend sphinxcontrib.rsvgconverter, because in my experience, the conversion was better than when using sphinxcontrib.inkscapeconverter (sadly, I don't find any examples anymore to prove that). Also, IIRC, the size of the installation (and probably the memory usage?) was smaller when using rsvg-convert.

I don't have any experience with LaTeX's svg package, so I don't know how it compares to sphinxcontrib.inkscapeconverter, but I guess it has (at least) the same downsides as I mentioned in the previous paragraph.

[jfbu]

Having read the comments python/cpython#140342, I wonder if simplest would not be there to simply add a pdf version of the svg to the cpython docs sources.

[m-aciek]

Having read the comments python/cpython#140342, I wonder if simplest would not be there to simply add a pdf version of the svg to the cpython docs sources.

And including in the docs in combination with only directive, right?

[jfbu]

Having read the comments python/cpython#140342, I wonder if simplest would not be there to simply add a pdf version of the svg to the cpython docs sources.

And including in the docs in combination with only directive, right?

No, simply using .* as extension in the image or figure directive should let Sphinx automatically pick the .pdf for the LaTeX build. And the .svg for html build. I tested right now and this feature does work.

[jfbu]

Regarding this proposal, my opinion is that this should not be done. The primary reason being that the svg package requires to run the PDF builds using --shell-escape which is simply absolutely a "no we will never do that" situation. The second one is that Inkscape is too large a dependency, and more importantly, the way of using it (hence the way to configure how to use svg) is too much system-dependent, and Inkscape version dependent.

The situation is:

• LaTeX can not natively handle svg,
• It is very difficult for us to ship something which will be able to convert on the fly from svg format to PDF,
• But we support since ages the .* syntax for image inclusion,
• So it is up to user to provide SVG images also in PDF format if a PDF build is desired.

[gmilde]

Docutils 0.22 supports the "svg" package as an "opt-in" feature: only if the user loads "svg" via the stylesheet option. Cf. Docutils commit [r9999]

An alternative is using the "rubber" building system (https://pypi.org/project/latex-rubber/) for the LaTeX run.
Rubber converts SVG to PDF with Inkscape "on the fly".

[jfbu]

* So it is up to user to provide SVG images also in PDF format if a PDF build is desired.

I should have repeated, for those who have Inkscape on their system, @mgeier's mention of

'sphinxcontrib.inkscapeconverter' or 'sphinxcontrib.rsvgconverter': See https://github.com/missinglinkelectronics/sphinxcontrib-svg2pdfconverter for installation instructions.

as it is much preferable to have such a Python level approach than using a LaTeX level approach requiring --shell-escape.

In a way this is the simplest working approach but it is hard for us to support it at Sphinx level, because it is a third-party extension and it needs user to customize where the Inkscape binary will be found, which is installation dependent.

In my view, having the build process systematically re-convert from svg to pdf is a waste of resources. Simply do it once and for all, join the pdf versions of images to the project, and enjoy .* Sphinx syntax.

[m-aciek]

The underlying issue in CPython has been resolved using sphinxcontrib-svg2pdfconverter. I am closing this issue due to arguments stated in #13953 (comment).