如何在 sphinx 文档中嵌入 <picture> 标签？

Question

我发现了以下问题： How do we embed images in sphinx docs?

然而，此图像标签假定文件为 jpg 或 png：

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

问题是 jpg 和 png 不是现代格式（还在 Lighthouse/Google PageSpeed Insights 中创建了一个糟糕的速度索引：）。我想将 html 标签与包含两种格式的两个相同文件的 srcset 一起使用。类似的东西：

<picture>
   <source srcset="diagram.avif" type="image/avif">
   <img src="diagram.jpg" width="620" height="540">
</picture>

这将为所有现代浏览器提供较小的图像，但将为不支持 avif 的浏览器（例如 IE）提供 png。你怎么能在 sphinx 文档/RST 中做到这一点？

Answer 1

使用 raw 指令和您的代码。

.. raw:: html

    <picture>
      <source srcset="diagram.avif" type="image/avif">
      <img src="diagram.jpg" width="620" height="540">
    </picture>

要复制任意静态文件，将它们放在与文档源文件相关的目录中，比如 _static，将文件放在那里，然后在 [=15] 中配置值 html_static_path =].例如：

html_static_path = [
    '_static',
]

Answer 2

你也可以用sphinxext-photofinish，文档有点欠缺，不过一般来说，你的图片标签可以保留为：

.. image:: picture.jpg
   :alt: Alt Text

而且它应该会自动生成一个<picture>标签，尝试转换为.webp并填写width/height。如果您想查看示例，它在 frc-docs 中使用。

如何在 sphinx 文档中嵌入 <picture> 标签？

How do you embed a <picture> tag in sphinx docs?

html

restructuredtext

python-sphinx