11

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.

Anyone know how to "tag" sections as "HTML build"-only and "Latex build"-only?

Cheers

Chris Morgan
  • 86,207
  • 24
  • 208
  • 215
Reuben Peter-Paul
  • 1,550
  • 3
  • 15
  • 25

2 Answers2

21

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.
mzjn
  • 48,958
  • 13
  • 128
  • 248
  • 1
    Thanks @mzjn .. only:: is exactly what I was looking for :) I remember seeing it in the docs and thinking I would need it someday and then I promptly forgot it and couldn't find it again! Cheers! – Reuben Peter-Paul Jun 27 '11 at 13:42
  • Perfect! This works for having the HTML builder use an SVG, and LaTeX to use a PDF as an image. – davidjb Aug 04 '15 at 06:33
12

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']
NickF
  • 469
  • 4
  • 7