Sphinx图片

在Sphinx中，有两种图片嵌入方法 image 和 figure :

  • image 是一种简单图片

  • figure 则提供了更多选项: 图像数据（包括图像选项）、可选标题（单个段落）和可选图例（任意正文元素）。对于基于页面的输出媒体，如果有助于页面布局， figure 可能会浮动到不同位置

使用案例

  • image 代码案例:

.. image:: picture.jpg
   :width: 200px
   :height: 100px
   :scale: 50 %
   :alt: alternate text
   :align: right

  • figure 代码案例:

.. figure:: picture.png
   :scale: 50 %
   :alt: map to buried treasure

   This is the caption of the figure (a simple paragraph).

备注

我之前使用过一段时间 image ，后来转为 figure ，简单使用并没有太大差异。

图像格式

我在撰写文档的时候，经常会截图(并简单标注一下)，由于通常在 macOS 桌面工作，所以我截图往往使用IM软件内置的截图工具并简单标注，然后将图片复制到macOS自带的 preview 程序，能够简单缩放然后保存成 png 或 jpg 文件。

不过，我也发现了不论是 png 还是 jpg ，文件都比较庞大，特别是现在高分辨率屏幕，简单的截图都会达到几百K甚至上兆。实际上，这对WEB页面非常不友好(虽然现在大家带宽都很大，但是我感觉还是消耗了太多资源)。

惭愧，最近才注意到 webp 格式图片，可以将相同的 png 缩小到 1/4 大小而没有什么画质影响。而且 Sphinx 也支持嵌入 webp 图片，这对编写电子书非常友好。

图像格式转换

macOS 内置的 preview 不支持 webp 格式图片，不过Linux提供了 libwebp 库工具来进行格式转换:

  • dwebp : 将 webp 转换成其他图像格式(decode)

  • cwebp : 将其他图像格式转换成 webp (encode)

举例:

dwebp image.webp -o final.png

dwebp image.webp -o final.jpeg

cwebp image.png -o image.webp

建议将图像转换成 webp 格式，这个图像格式目前得到所有主流浏览器支持，可以大大节约图像下载占用的带宽。

备注

可以使用 parallel 工具并发转换大量图片，充分利用多处理器的性能

参考