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 ?

Solution 1

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.

Solution 2

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).

Solution 3

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)