如何嵌入<图片>sphinx 文档中的标签？

发布于 2025-01-15 07:37:58 字数 718 浏览 2 评论 0原文

但是这张图片标签假定文件格式为 jpg 或 png：

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

问题在于 jpg 和 png 不是现代格式（还会在 Lighthouse/Google PageSpeed Insights 中创建错误的速度指数：

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

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

原文

I have found the following question:
How do we embed images in sphinx docs?

However this image tag assumes the file is in jpg or png:

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

The issue with that is that jpg and png are not modern formats (also creates a bad speed index in Lighthouse/Google PageSpeed Insights: ). I would like to use a html tag with a srcset containing of two identical files in two formats.
Something like that:

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

This will serve the way smaller image to all modern browsers, but will serve the png to browsers which don't support avif (e.g. IE). How can you do that in sphinx docs / RST?

分享到QQ

分享到微博

如果你对这篇内容有疑问，欢迎到本站社区发帖提问参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。

发布评论

需要登录才能够评论，你可以免费注册一个本站的账号。

瑶笙 2025-01-22 07:37:58

使用 raw 指令和您的代码。

.. raw:: html

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

要复制任意静态文件，请将它们放在与文档源文件相关的目录中，例如 _static，将文件放在那里，然后配置值 html_static_path 在您的 conf.py 中。例如：

html_static_path = [
    '_static',
]

Use the raw directive and your code.

.. raw:: html

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

To copy arbitrary static files, put them in a directory relative to the documentation source files, say _static, place the files there, and then configure the value html_static_path in your conf.py. For example:

html_static_path = [
    '_static',
]

回复收藏 0 原文

流心雨 2025-01-22 07:37:58

您还可以使用 sphinxext-photofinish，文档有些缺乏，但总的来说，您可以将您的图像标签保留为：

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

它应该自动生成标签，尝试转换为 .webp 并填写宽度/高度。如果您想查看示例，它可以在 frc-docs 中使用。

You can also use sphinxext-photofinish, the docs are somewhat lacking, but in general, you can leave your image tags as:

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

And it should automatically generate a <picture> tag, try to convert to .webp and fill in the width/height. It is used in frc-docs if you want to see an example.

回复收藏 0 原文

~没有更多了~