[Sphinx] Inserting Media in Restructured Text (ReST) Files

If you are building documentation using Sphinx (python static site generator), you'll have to learn a plain markup language called ReStructured Text (ReST). ReST has a pretty unique syntax all around, so if you're wondering how many ways we can insert media in this file, keep on reading!

So, in order to follow this tutorial you must at least have a basic understanding of the reST syntax. Knowing what a directive is is enough to get you started.

To insert media such as images or gifs, use directives like so:

.. image::

.. figure::

.. thumbnail::

● If you want to insert an image or GIF with a caption, use the figure directive.
● If you want to insert an image or GIF that can be enlarged when you click on it (also known as Lightbox), use the thumbnail directive. In practice, it’s better to always use this directive for images
● Use image directive to insert small icons or buttons. Since this directive can be used for substitution definition.

Thumbnail

Personally, you should use Thumbnail in most of your images as this is the most customisable directive for media. Unfortunately, this is not a built-in feature in Sphinx so it comes as an extension. To use this directive, you must install it first and then configure your conf.py file by adding the lightbox extension.

Installing Lightbox

• Run the following command pip install sphinxcontrib-images.
• After the package has been successfully installed, open your conf.py file and add the following extension:

 extensions = [
          …
          'sphinxcontrib.images',
          …
          ]

• Additionally, you can further customise image behavior, i.e., width, height, download or title in the conf.py by adding this parameter:

 images_config = {
    …
 }

For example:

 #lightbox behavior
 images_config = dict(backend='LightBox2',
 default_image_width='100%',
 default_show_title='True',
 default_group='default', )

• Now, you can start using the .. thumbnail:: directive in your ReST file. Here's an example:

 .. thumbnail:: path/to/image.png
  :alt: some image
  :align: center
  :title: some image title

The title attribute here is a caption that appears when the lightbox takes effect, that is when you zoom in on the image. You can use the similar wording for both the title and alt texts.

Other attributes you can use for the Thumbnail directive are:

• :download: True This lets you to download remote images.
• :width: and :height: These are pretty self-explanatory. If you define this as in your image attribute, it will override the default backend configuration you defined in your conf.py.
• :group: This will tell the backend to group different images together.

Figure

You can enlarge images on click using this directive, but the zoom in effect is not as smooth as the Thumbnail one. This is a built-in feature in Sphinx though so you don't need to install any extensions first.

Example of using the Figure directive:

.. figure:: path/to/image.png
  :width: 200px
  :height: auto
  :alt: some alt text

 _insert image caption here_

If you see above, you can directly insert image captions with figure as long as it's still indented right under the .. figure:: directive (remember, ReST is very sensitive to indentation!).

Image

This can be your last resort if, for some reason, those two directives do not work. However, in practice you can use this for when you need to reuse the same image in different pages of your documentation. This means, you can insert the image by simply using a pre-defined keyword.

For example, you want to insert an inline icon in the same sentence.

click the Exit button |button-icon| to close the application

in the same file, preferably at the bottom of the file you can define the image substitution as follows:

.. |button-icon| image:: path/to/image.png
  :width: 30

and voila! you'll have an inline icon in your output. :)

That's all! Enjoy working with Sphinx. Ciao Kakao.