Is it possible to link to an thumbnail?

[creepingArrow]

Hello, I've just started working with sphinx and also just created a github account. This is kind of a How To Question or feature request. I was amazed to find such a nice extension for HTML images. Unfortunately I was not able to create a link to the image.

My first thought was: I should use .. figure:: instead of .. image:: (or .. thumbnail:: ) but the nice automatic integration of lightbox seems to be possible for ..image:: only.

Now for my Question: Is there a way to link to the ..thumbnail:: or is there a way use the lightbox with fiigures?

What I've tried:

.. _imagetest:

.. thumbnail:: media/sphinx_jpgExample.jpg
 :title: This image has title.

 And more descriptions.

link to thumbnail: :ref:`imageLink` :ref:`own text<imageLink>`

Greetings Falk

[jonascj]

There is another issue regarding the figure directive: https://github.com/sphinx-contrib/images/issues/15 .

With figures you can have the figures numbered and you can reference them in text as a link Fig. 1 (see example below). This is not possible with .. thumbnail:: since they can not be numbered and do not have a title or caption like figures. Hence there is nothing meaningful to insert when they are reference (no title for See Installation and no number for See Fig. 1).

It would be super useful though, so someone could still look at implementing it. My feeling is that it is possible to implement, maybe with a feature or two less than the full figure directive. #15 mentions translations as being a problem.

Example Figure with numbering and reference

.. _python logo:

.. figure:: python.png

   The Python logo

 The Python logo is shown in :numref:`python logo`.

which with numfig = True in conf.py will result in the figure being numbered and the text with :numref: being rendered as:

The Python logo is shown in Fig. 1.

[creepingArrow]

Thank you for your fast and detailed answer.

I think I need to determine how important the numbering and linking for images is for my use case. Unformtunately I don't have the knowledge and (standard excuse) not enough time to implement a figure extension.

Thus I want to say a big thank you. Even without the figures it is a very nice feature with an reasy and useful handling.

[jonascj]

You're welcome. When you say 'link to .. thumbnail::' you seem to mean 'reference a .. thumbnail::' or 'cross reference a ..thumbnail::', which as you say creates a link to that image. Consider using 'reference' instead of 'link' when searching for this topic.

I'm not the original author of the plugin, just the current maintainer, and I know what you mean when you say you need to determine the importance of numbering and referencing vs. the lightbox (full size) feature. I got involved in this project because I wanted the lightbox (popup / full size images) in my sphinx 2 project and at the time this extension only supported sphinx 1.8. After helping to port the plugin to sphinx 2.0 I stopped using the plugin for most things because I needed numbering and references.

So I consider it an important thing to get it working with the .. figure:: directive or have .. thumbnail:: be numbered and be able to reference them.

[creepingArrow]

Oh yes, reference is the correct word and I should use it.

I found something. Images itself (without the extension) can be referenced if a name is given:

.. _refexample:

.. image:: media/sphinx_svgExample.svg

:ref:`example reference to image<refexample>`

With the extension, this doesn't work anymore. I think because there are other things added in HTML. By chance I added a comment in the sphinx code and then the reference to images works with the extension.

.. _refexample:

.. (reference will lead to this point), this comment line is important

.. image:: media/sphinx_svgExample.svg

:ref:`example reference to image<refexample>`

With this ugly workaround I can use the lightbox and link to images with manual choosen link text. It was decided that in my case the numbering of figures and automatic named references are less important than the lightbox usability. So for me it works, despite the fact that a comment in the code changes something in the result hurts a little.

I'm not sure if this is correlated to the theme. currently I'm using the standard alabaster.

Greetings Falk

[jonascj]

I stand corrected. You are of course right, .. image:: whatever.jpg can be referenced as :

.. _target whatever:

.. image:: whatever.jpg

An image of whatever can be seen here: `target whatever`_.

An image of whatever can be seen here: :ref:`Whatever <target whatever>`.

With link text target whateverand Whatever respectively.

But it can not be referenced with :numref: since images are not numbered. Relevant documentation being [1] and [2].

For me it makes no difference whether sphinxcontrib.images is loaded/included or not. Maybe you have the images_config = {'override_image_directive': True} which effectively makes all your .. image: directives into .. thumbnail:.

Your hack or workaround seem to be utilizing the ability to create explicit targets anywhere in a document and then referencing it. I.e. you make a target for a comment, which is located close to the thumbnail, and reference that instead [1].

[1] https://docs.readthedocs.io/en/stable/guides/cross-referencing-with-sphinx.html [2] https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html#cross-referencing-documents

[jonascj]

@creepingArrow I've fixed this in commit https://github.com/sphinx-contrib/images/commit/8051f71f6c85dca1b9cf11ffbdac04a80a089ff5. I'll release as version 0.9.4 tomorrow.

[jonascj]

0.9.4 released with this fix.