Linking to figures in Sphinx

Question

I have some images in my documentation created as a set of reST files in Sphinx. I prefer to keep them pretty small, and I want the user to click on them to get the larger image. The smaller image is not for file size reasons but for presentation reasons. I do not find a syntactic way to combine the tags image: or figure: with ref: or link:.

.. image:: _static/my_image_small.png

and I have a bigger version 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. Is there a way to bypass the Sphinx generator and just give the HTML that I want?

Answer 1

There are two ways you can do it.

The first is to just insert a bit of "raw" HTML:

.. raw:: html

    <a href=....><img src=....

The second is to make the image clickable. That way you can link it to a bigger image:

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

There are more options you can give, btw. See the full list in the restructured text documentation.