[Sphinx] Inserting Media in Restructured Text (ReST) Files
Tags: python, sphinx, restructured, rest
Published: 2022-07-13 07:34:40

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](https://www.sphinx-doc.org/en/master/usage/restructuredtext/directives.html) 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:

 ```cpp
 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:

 ```cpp
 images_config = {
    …
 }
 ```

 For example:

 ```python
 #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:

 ```python
 .. 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:

```python
.. 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:

```python
.. |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.