Sphinx: no SVG support in PDFs

[anarcat]

Coming from https://github.com/rtfd/readthedocs.org/issues/905 here... it looks like Sphinx doesn't support SVGs properly. Or, more accurately, the LaTeX file it generates asumes that \includegraphics can deal with SVG files: it can't.

In LaTeX, SVG images are special: they need to be first converted into another format using Inkscape, and the SVG package. More information about this is available in this TeX stackexchange question, but basically, if a .svg file extension is detected, sphinx should generate the following, in the preambule:

\usepackage{svg}

and instead of \includegraphics, use:

\includesvg{file}

Notice how the .svg file extension should _not_ be provided. It may be possible to hack up something to replace the \includegraphics{} directive so it calls \includesvg when there's a .svg extension, but i would recommend against that confusing tactic and generate the right directive straight from Sphinx.

Of course, Inkscape needs to be available (in the path, or the path can be specified in the preambule, with \usepackage[inkscape={/opt/bin/inkscap‌​e -z -C}]{svg}) and --shell-escape must be passed on the commandline. It may be interesting to allow inkscape parameters to be overridable from the conf.py of course.

A workaround is to generate a PNG file by hand on the side, then include the right file depending on the ouput format:

.. only:: latex

  .. image:: file.png

.. only:: html

  .. image:: file.svg

Then, to generate file.png, one could add this to the makefile:

%.pdf: %.svg
    inkscape --without-gui --export-area-drawing --file=$< --export-pdf=$@

You could also add targets to the makefile to make sure those images are built automatically:

SOURCEDIR     = source
#IMAGEDIRS can be a list of directories that contain SVG files and are relative to the SOURCEDIR
IMAGEDIRS      = _images _images2 ...

PDFs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.pdf,$(wildcard $(SOURCEDIR)/$(dir)/*.svg)))

images: $(PDFs)

# make sure PDFs are cleaned
clean:
    -rm -rf $(BUILDDIR)/*
    -rm $(PDFs)

latex: images
    # [...]
latexpdf: images
    # [...]

(Inspired in part by this tutorial.)

But that's kind of a horrible hack that shouldn't be necessary.

[nemesisdesign]

I also incurred in this issue. Are the commits pushed to openstack useful?

[PowerKiKi]

I don't think so. It seems to be a workaround on a non-related project unfortunately

[xuhdev]

I've made a PR #2166 to solve this issue. Please check it out if you are interested :)

[tk0miya]

Now sphinx.ext.imgconverter is bundled. In addition, Sphinx provides to an API to convert images with own tooling.
http://www.sphinx-doc.org/en/stable/ext/imgconverter.html

So I'm closing this now.
Thanks,

[anarcat]

@tk0miya is sphinx.ext.imgconverter enabled by default?

[tk0miya]

Please take a look the name. It's an extension. So please enable it in your conf.py :-)
In addition, it uses imagemagick inside. So you need to install it on execution.

[bernaloo]

Hi, thanks for the update.
after including sphinx.ext.imgconverter in the list of extensions inside the conf.py file,
how does the including of a svg graphic should be done?
.. image:: test.svg
does not work for me
thanks

[tk0miya]

Yes, please use image or figure directive.
Could you file a new issue with your logs and inputs.
Thanks,