Sphinx adding a link to an image or a figure

Question

I am trying something rather basic in Sphinx. I have some images, but I prefer to keep them pretty small, and I want to allow the user to click on them to get the larger image. I do not find a syntactic way to combine image: or figure: with ref: or link:.

.. image:: _static/my_image_small.png

and I have in the same folder my_image_large.png.

If you come up with a solution, should the larger image just be a file with an explicit link to it or do I create a reSt file with an additional image: tag? An alternative could be to play with the image sizes in the reSt file, but then I still do not know how to create the link from the small image to the large image.

Thank you for helping me.

Answer 1

Just use the target directive. You would end up with something like:

.. image:: _static/my_image_small.png
   :target: _static/my_image_large.png

It is not strictly necessary to use the references to the static folder in your source. They will be copied to the _images folder anyway when you build the docs (so you will have them twice in your builds, without needing them there).

I always use a folder called figures next to the source folder where I manage the images. The my_image_large.png files, however, you would want to place in the _static folder as the contents will be copied on build.