Thumbnail-like behavior using target attribute of image directive

Question

I use Sphinx to generate some docs. I have a reStructuredText document and I'd like to put an image into it. The case is that the image should be clickable so that after a user clicks the image then they should be shown this image in full size. I use the image directive and its target option like this:

.. image:: /images/some_image.png
   :alt: Image descripion
   :align: center
   :target: `big_some_image`_

.. _big_some_image: /images/some_image.png

The problem is that in the rendered page I get:

<a href="/images/some_image.png"><img src="../../../_images/some_image.png"></a>

So there is correct src from the image directive but an incorrect href attribute from the hyperlink.

Questions:

• is there any way to generate links in the way that image directive does it? I mean relative to the document.

• is there any other (built in) way to have "thumbnail-> click -> big image" behaviour?

Answer 1

Simply use the scale option:

.. image:: large_image.png
    :scale: 20%

When the scaled image is clicked on, the full image loads in its own window. So this doesn't increase the image size on the page, but that would be messy anyway.

Answer 2

When you use the image directive from within Sphinx, Sphinx does some special handling to find the image file and copy it into your project (like your _images directory), and then renders the HTML to point to that place.

But the target option just takes a URL as a parameter. It knows nothing about your Sphinx project, or how your images are laid out, and does not attempt to guess.

If you want to have it point to a larger version of the same file, you will likely need to do some manual steps (like maybe copying the file to a specific location), or maybe provide a relative URL to the large file, rather than the absolute URL you have in your example.

If you want to go a completely different way, you could also try overriding and modifying the HTML templates for your project to add some JavaScript to get the click-to-larger-image effect you want.

Answer 3

Looks like there is a Sphinx extension that does this now, and quite nicely at that, sphinxcontrib-fancybox 0.3.2. Install with pip, add it to your extensions in conf.py, and use the fancybox directive:

.. fancybox:: images/image.png

Answer 4

Relative links seem to work. For the Mapserver docs setup, if an image is placed in the images directory, a relative link like in the following code works in my local build. Here is an example using figure (the underscore ("_") before "images" in the target link is necessary):

.. figure:: ../../images/carto-elements.png
  :height: 400
  :width: 600
  :align: center
  :target: ../../_images/symcon-overlay.png