Thank you, @geographika!
This is is a very useful illustration. But I am not sure if the _static directory is the right place for the full image (map_classes_full.png). I would think that the image directory could be the right place. I will let @jmckenna decide.

@havatv is correct, the image should live in the /en/images/ directory.

I tried the following RST but the target image isn't copied across when building (the resized smaller image is fine):

.. image:: ../images/layer_classes.png
    :align: center
    :target: ../images/layer_classes_full.png

The :scale: property works, but requires pillow to be installed, and the image is a little more blurred:

.. image:: ../images/layer_classes.png
    :align: center
    :scale: 80%

Maybe I can drop the full sized image completely?

As far as I can tell, :target: has not been used for images in the image directory before, so I am not sure how it is done.
You could try the following for the target: _images/layer_classes_full.png
../_images/layer_classes_full.png might also work.

I've tried several ways but it doesn't seem like it is supported. See https://stackoverflow.com/a/13075141/179520

The only 3 options appear to be:

• leave the larger image in static (the resized image is already in /en/images/
• add pillow to requirements.txt and use the :scale: tag (this takes care of resizing and clickable link)
• remove the full size image available when clicking on the smaller version

Let me know which option best suits the project.

I tried to link to an image located in /images from construction.txt in the en/mapfile/symbology directory, and this works for me in a local build::

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

@havatv - thanks for that suggestion. The main issue was that the image file doesn't get copied automatically from the /image/ folder to the built /_images/ folder when using the :target: directive.
However I can manually set the width and height on the image, and link to itself via the _images folder as suggested.

@geographika, I did not see that problem - but you solved it nicely!

Thank you for this very useful contribution, @geographika!