使用Sphinx文档如何为Latex/PDF构建指定HTML构建和pdf图像格式的png图像格式？

Question

使用sphinx doc生成器,我试图将.png图像用于文档的HTML构建,然后我想将.svg图像用于PDF/LATEx构建.

任何人都知道如何"标记"部分为"HTML构建" - 只有"乳胶构建" - 只是？

干杯

Answer 1

看看这些选项:

1. 图像文件名通配符:

   .. image:: gnu.* 
   

   从文档中:"例如,如果给出了文件名gnu.*并且源树中存在两个文件gnu.pdf和gnu.png,则LaTeX构建器将选择前者,而HTML构建器则更喜欢后者. "

2. 该only指令:

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

Answer 2

可以使用makefile自动构建适当的输出格式.

还提供了一个教程,演示了使用Sphinx和SVG以及LaTeX PDF输出的类似过程.

1. 在.rst源中使用图像文件名通配符选项.

   .. image:: my_image.*
   

2. 使用Inkscape在构建时将源图像转换为PDF和PNG.您可以通过在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
   

   最后,更新clean,latex以及latexpdf规则对相应图像目标的相关性:

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

   现在,您可以通过键入make images并清理它们来构建图像make clean-images.使用make html,make latex并make latexpdf会自动确保您的图片上最新的.

3. 一个问题是Sphinx默认在HTML输出中更喜欢SVG而不是PNG.您可以通过覆盖conf.py文件中的preferece来解决此问题.

   conf.py导入后,在文件顶部附近添加以下行.

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