Sử dụng tài liệu Sphinx làm cách nào tôi có thể chỉ định định dạng hình ảnh png cho các bản dựng HTML và định dạng hình ảnh pdf cho các bản dựng Latex/PDF?

Question

Sử dụng trình tạo tài liệu nhân sư, tôi đang cố gắng sử dụng hình ảnh .png để xây dựng tài liệu HTML và sau đó tôi muốn có hình ảnh .svg được sử dụng cho các bản dựng PDF/LATEx.

Bất kỳ ai biết cách "gắn thẻ" các phần dưới dạng "HTML build" -only và "Latex build" -only?

Cheers

Answer 1

Hãy nhìn vào các tùy chọn này:

1. ảnh filename wildcard:

   .. image:: gnu.* 
   

   Từ documentation:. "Ví dụ, nếu tên tập tin gnu * là cho trước và hai tệp gnu.pdf và gnu.png tồn tại trong cây nguồn, trình tạo LaTeX sẽ chọn tệp cũ, trong khi trình tạo HTML sẽ thích cái sau. "

2. Các only chỉ:

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

Answer 2

Có thể sử dụng makefile để tự động xây dựng các định dạng đầu ra thích hợp.

Hướng dẫn chứng minh quy trình tương tự cho using Sphinx with SVG and LaTeX PDF output cũng khả dụng.

1. Sử dụng hình ảnh filename wildcard option trong nguồn .rst của bạn.

   .. image:: my_image.* 
   

2. Sử dụng Inkscape để chuyển đổi hình ảnh nguồn thành PDF và PNG lúc xây dựng. Bạn có thể làm điều này tự động xây dựng theo thời gian bằng cách thêm đoạn mã sau vào Makefile của bạn:

   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 
   

   Cuối cùng, cập nhật các quy tắc clean, latex và latexpdf để có một sự phụ thuộc vào các mục tiêu hình ảnh tương ứng:

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

   Bây giờ bạn có thể tạo hình ảnh của mình bằng cách nhập make images và xóa chúng bằng make clean-images. Sử dụng make html, make latex và make latexpdf sẽ tự động đảm bảo hình ảnh của bạn được cập nhật.

3. Một vấn đề là Sphinx mặc định thích sử dụng SVG hơn PNG trong đầu ra HTML. Bạn có thể sửa lỗi này bằng cách ghi đè quyền ưu tiên trong tệp conf.py của mình.

   Thêm các dòng sau gần đầu tệp conf.py của bạn sau khi nhập.

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