Using Sphinx documents, how can I specify png image formats for HTML collections and PDF image formats for creating Latex / PDF?

Question

Using the sphinx doc generator, I try to use .png images for HTML assembly documentation, and then want .svg images to be used for PDF / LATEx assembly.

Does anyone know how to "tag" sections as an "HTML assembly" - only "Latex build" - only?

Greetings

Answer 1

Take a look at the following options:

• A wildcard file with an image file name:

  .. image:: gnu.* 

  From the documentation : "For example, if the file name gnu. * And two files gnu.pdf and gnu.png were specified in the source tree, LaTeX builder will select the first, while the HTML constructor will prefer the latter."

• only :

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

Answer 2

You can use the makefile to automatically build the appropriate output formats.

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

• Use the file wildcard parameter in the .rst source.

   .. image:: my_image.* 

• Use Inkscape to convert source images to PDF and PNG files at build time. You can do this automatically during build 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 to be dependent on the corresponding image goals:

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

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

• One problem is that Sphinx, by default, prefers SVG over PNG in HTML output. You can fix this by overriding preferences in your conf.py file.

  After importing, add the following lines at the top of your conf.py file.

   # 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']