html_scaled_image_link behavior is too restrictive for extension developers

[danwos]

I'm developing sphinx-extensions and my code is using nodes.image from docutils to add images to the documentation which shall be used as buttons, status or other indicators.

But Sphinx is surrounding my images with nodes.reference, so that they become clickable links, which open the image in the browser.

This is not the desired behavior, as I bind the images to javascrip (html only) to use them as buttons for specific actions.

Problem

sphinx/sphinx/builders/html.py

Line 808 in cad1f86

if self.config.html_scaled_image_link and self.html_scaled_image_link:

The handling of html_scaled_image_link does only look on the global config, but not on the image node itself, if maybe some attributes are set to avoid adding of references.

So I can only switch off the behavior globally, which for sure is not an option.

Solution / Proposal
I propose the usage of a target attribute of the image node.
If this is set, the target-value is used as refuri.
If it is set to None but part of node.attributes-dict, no reference should be added.
If it is not set (which is currently always the case), normal handling as of now.

As far as I have understood the docutils code, the handlers of images-nodes do not care about a target attribute.

Workaround
Luckily I found on, but it is very ugly.

First off all, you need to add the image-node to a reference-node.
In this case, the html_scaled_image_link handling is aborted, as it stops if parent of an image-node is already a reference-node.

But now you have a not wanted reference in your html-code, which forces the browser to jump/scroll the page when clicked on it.
So I must use some javascript to avoid this :(

Here the code for the important parts:

# Wrap image-node inside a reference node
...
ref_node = nodes.reference('', '', refuri='#', classes=['no_link'])  # Set a specific class for later js handling
ref_node.append(image_node)
return ref_node

A loaded js-file needs to have this in it:

// JQuery is used here
$(document).ready(function() {
    $('a.no_link').click(function (e) {
        e.preventDefault();
    });
});

So, what do you think?.
I feel not really happy with the proposed solution.
Maybe someone else has a better idea, how to "deactivate" this behavior for sphinx extension developers.

[tk0miya]

I think it would be better if users also can control the scaled-image-links, not only from extensions. So I propose you to use "classes" attribute instead. What do you think?

My idea:

.. image:: path/to/image.png
   :scale: 50%
   :class: no-scaled-link

[danwos]

Awesome, great idea.
And thanks for the really quick implementation.
I'm happy with it.