How do you embed a tag in sphinx docs?

Question

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?

You are missing a closing `>` on `` in your last example. Could that be the problem? — Rob, Mar 17 '22 at 14:35
That in fact was missing, but that was just an example HTML code. Can't use that in sphinx. — Felixkruemel, Mar 18 '22 at 15:08

Steve Piercy · Accepted Answer · 2022-03-24T08:56:40.713

1

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

edited Mar 24 '22 at 08:56

answered Mar 17 '22 at 15:35

Steve Piercy

13,693
1
44
57

How can you let sphinx copy the images correctly in that case? As they aren't included as image tag they won't be copied when generating html – Felixkruemel Mar 22 '22 at 14:32
1

I've updated my answer for how to copy arbitrary files. – Steve Piercy Mar 24 '22 at 08:57

score 0 · Answer 2 · answered Mar 20 '22 at 13:08

0

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.

answered Mar 20 '22 at 13:08

Itay Ziv

76
1
2
6

Hey @Itay Ziv, How do you specify the alternative images formats with it? If it automatically converts it to webp, can it also do that to avif? If not I think I would open an issue on GitHub, might be useful. – Felixkruemel Mar 21 '22 at 17:49
Also I really don't know how to use it. Added it to the extensions, still doesn't do anything to image or figure tags... – Felixkruemel Mar 22 '22 at 14:13

How do you embed a tag in sphinx docs?

2 Answers2