Using Sphinx docs how can I specify png image formats for HTML builds and pdf image formats for Latex/PDF builds?

Question

Using sphinx doc generator, I am trying to use .png images for the HTML builds of the documentation, and then I want to have the .svg images used for the PDF/LATEx builds.

Answer 1

It is possible to use the makefile to automatically build the appropriate output formats.

A tutorial demonstrating a similar process for using Sphinx with SVG and LaTeX PDF output is also available.

1. Use the image filename wildcard option in your .rst source.

   .. image:: my_image.*
   

2. Use Inkscape to convert your source images into PDFs and PNGs at build-time. You can do this automatically at build-time by adding the following code to your Makefile:

   SOURCEDIR     = source
   #IMAGEDIRS can be a list of directories that contain SVG files and are relative to the SOURCEDIR
   IMAGEDIRS      = _images
   
   # SVG to PDF conversion
   SVG2PDF       = inkscape
   SVG2PDF_FLAGS = -C
   
   # SVG to PNG conversion
   SVG2PNG       = inkscape
   SVG2PNG_FLAGS = -C -d=90 --export-background-opacity=\#00
   
   # Pattern rule for converting SVG to PDF
   %.pdf : %.svg
       $(SVG2PDF) $(SVG2PDF_FLAGS) -f $< -A $@
   
   # Pattern rule for converting SVG to PNG
   %.png : %.svg
       $(SVG2PNG) $(SVG2PNG_FLAGS) -f $< -e $@
   
   # Build a list of SVG files to convert to PDFs
   PDFs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.pdf,$(wildcard $(SOURCEDIR)/$(dir)/*.svg)))
   
   # Build a list of SVG files to convert to PNGs
   PNGs := $(foreach dir, $(IMAGEDIRS), $(patsubst %.svg,%.png,$(wildcard $(SOURCEDIR)/$(dir)/*.svg)))
   
   # Make a rule to build the PDFs
   images-pdf: $(PDFs) 
   
   # Make a rule to build the PNGs
   images-png: $(PNGs) 
   
   # Make a rule to build the images
   images: images-pdf images-png
   
   clean-pdf:
       -rm $(PDFs)
   
   clean-png:
       -rm $(PNGs)
   
   clean-images: clean-pdf clean-png
   

   Finally, update the clean, latex and latexpdf rules to have a dependency on the respective image targets:

   ...
   clean: clean-images
   ...
   html: images-png
   ... 
   latex: images-pdf
   ...
   latexpdf: images-pdf
   ...
   

   Now you can build your images by typing make images and clean them with make clean-images. Using make html, make latex and make latexpdf will automatically make sure your images are up-to-date.

3. One problem is that Sphinx defaults to preferring SVG over PNG in HTML output. You can fix this by overriding preferece in your conf.py file.

   Add the following lines near the top of your conf.py file, after imports.

   # Redefine supported_image_types for the HTML builder
   from sphinx.builders.html import StandaloneHTMLBuilder
   StandaloneHTMLBuilder.supported_image_types = ['image/png', 'image/svg+xml', 
                                          'image/gif', 'image/jpeg']
   

Answer 2

Take a look at these options:

1. Image filename wildcard:

   .. image:: gnu.* 
   

   From the documentation: "For instance, if the file name gnu.* was given and two files gnu.pdf and gnu.png existed in the source tree, the LaTeX builder would choose the former, while the HTML builder would prefer the latter."

2. The only directive:

   .. only:: latex
   
      This appears only in LaTeX output.
   
   .. only:: html
   
      This appears only in HTML output.