How do we embed images in sphinx docs?

Question

I am quite new in using sphinx, Doing documentation for the first time for the python project. How to embed image for example in the sphinx documentation ?

score 92 · Answer 1 · edited Jul 04 '17 at 01:35

From the documenation:

There are two image directives: image and figure.

An image is a simple picture.

A figure consists of image data (including image options), an optional caption (a single paragraph), and an optional legend (arbitrary body elements). For page-based output media, figures might float to a different position if this helps the page layout.

Example for image usage:

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

Example for figure usage:

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

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

devin_s · Accepted Answer · 2022-01-18T17:23:44.253

40

Use the image directive, for example:

.. image:: example.png

The path to the image is relative to the file. See the Sphinx documentation for more information.

edited Jan 18 '22 at 17:23

answered Sep 16 '14 at 22:52

devin_s

3,345
1
27
32

4

Also I can recommend trying out the `.. figure::` directive, as it has some nice features. – wswld Sep 17 '14 at 11:54

score 18 · Answer 3 · answered May 05 '20 at 16:47

18

In case anyone is looking to include an inline image, the following works:

The |biohazard| symbol must be used on containers used to dispose of medical waste.

.. |biohazard| image:: biohazard.png

(From https://docutils.sourceforge.io/docs/ref/rst/restructuredtext.html#substitution-definitions)

answered May 05 '20 at 16:47

Ken

1,691
5
22
38

1

Exactly what I was searching for, thank you! Once your image has been defined somewhere, the link (here `|biohazard|`) can be re-used inside the same documentation page easily. – jeannej Sep 07 '22 at 12:54

score 1 · Answer 4 · answered May 24 '22 at 11:31

1

Make sure there is a line between above the line that says .. image::

My image wasn't showing, but I just had to separate it from the text line that was above it.

answered May 24 '22 at 11:31

loftusmi3

11
1

score 1 · Answer 5 · answered May 24 '22 at 16:54

1

Since you have to use a relative path, I created a images directory, in which case I needed to use the following for the image path: .. image:: ..\\images\\image.png

answered May 24 '22 at 16:54

Trevor Arnold

76
4

As it’s currently written, your answer is unclear. Please [edit] to add additional details that will help others understand how this addresses the question asked. You can find more information on how to write good answers [in the help center](/help/how-to-answer). – Community May 29 '22 at 19:45

How do we embed images in sphinx docs?

5 Answers5

Linked