8000 Improve user experience in the user guide - make it clear to users that images are clickable · Issue #30596 · scikit-learn/scikit-learn · GitHub
[go: up one dir, main page]

Skip to content

Improve user experience in the user guide - make it clear to users that images are clickable #30596

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
marenwestermann opened this issue Jan 6, 2025 · 17 comments

Comments

@marenwestermann
Copy link
Member
marenwestermann commented Jan 6, 2025

Describe the issue linked to the documentation

In the user guide, it's not very noticeable that it's possible to click on images which then leads users to the example in which the respective image is used and explained in detail. For instance see here.

Suggest a potential alternative/fix

It would be good to find find a solution that makes it clear to users that there's a hyperlink attached to the images which leads to the respective examples. The discussion came up in PR #30127 which contributes to issue #26927.
@scikit-learn/contributor-experience-team @scikit-learn/documentation-team

@ogrisel ogrisel removed the Needs Triage Issue requires triage label Jan 7, 2025
@StefanieSenger
Copy link
Contributor
StefanieSenger commented Jan 7, 2025

I have missed that pictures might be clickable as well. Though I don't think that it had been too bad, since I am (like most people?) searching by text (inside-search or search bar) anyways when on the website.

Dimensions: A quick search for :target: ../auto_examples reveals that there might be 209 of such clickable images. Now, we could make these links explicit by duplicating them across the board or we could look at them one by one and evaluate if they add value to the file and make them explicit only then.

The first option is an overkill, I believe, and the second we're already doing in #26927. I would tend to trust this process.

I think if I'd be very interested in an image, I would see the cursor changes on them after a while.

@ogrisel
Copy link
Member
ogrisel commented Jan 7, 2025

I am aligned with the goal, but not sure what's the best way to achieve that.

@ogrisel
Copy link
Member
ogrisel commented Jan 7, 2025

I was thinking about using a new CSS rule such as:

figure > a > img::after {
  content: "Click on the plot to see the code that generated it."
}

but this was not enough, and I could not make it work after a few back and forth tweaks with perplexity.

@lucyleeow
Copy link
Member

I am not sure what the CSS above does so my suggestion may be redundant; what about a cursor tooltip with the text suggested above, that appears when you hover over the image?

@ogrisel
Copy link
Member
ogrisel commented Jan 8, 2025

I am not sure what the CSS above

I wanted to add a small text below such clickable images in the user guide. This text could be styled to be in italic and not as contrasted as the main text.

Maybe @Charlie-XIAO has an opinion on how we could make this work?

what about a cursor tooltip with the text suggested above, that appears when you hover over the image?

I find tooltips that follow the cursor a bit annoying personally. Furthermore, they do not help when browsing the doc on a mobile / tablet, or browsing on a desktop but without moving the mouse over the images of the doc (scrolling with the mouse with the cursor staying over the navigation panel).

@Charlie-XIAO
Copy link
Contributor
Charlie-XIAO commented Jan 8, 2025

I'm afraid that psuedo-elements like :after won't work for <img> so there might be no easy pure-CSS solution.

Alternatives:

  • Manually add captions. Easiest and no hack, but people can forget to add them.
  • Use JS. Fairly easy, but adds some overhead to the webpages, and does not work if JS disabled.
  • Sphinx post-transforms. Hacky and may significantly increase doc build time.
  • Override the figure directive to tweak what it generates. I'm not sure if this is possible (I will investigate).

@virchan
Copy link
Member
virchan commented Jan 8, 2025

This is the result after adding captions (the first alternative suggested by @Charlie-XIAO):

Screenshot 2025-01-08 151711

What I learned is that a blank line between the last directive option (:scale:) and the caption is necessary; otherwise, the figure will not appear in the HTML file.

The caption also looks good in different colour modes.

I also attempted to create a custom class for the figure directive in the doc/scss/custom.scss file to define hover behaviour, or add a frame around clickable images. However, none of these approaches worked (at least for the example above). I suspect this might be related to @Charlie-XIAO's comment:

psuedo-elements like :after won't work for <img>

as well.

If we decide to fix this for all clickable images, we could use the search method suggested by @StefanieSenger to manually update them on a large scale. It might be helpful to update the contributing guide to 8000 remind contributors during the creation or review of pull requests.

@StephenJudeD
Copy link

I agree this is an important UX improvement. Based on my experience in data visualization and UX, I'd suggest a minimally intrusive solution that maintains documentation clarity while improving discoverability:

  1. Add a small icon (e.g., 🔍 or 🔗) next to clickable images using CSS:
figure > a > img {
    cursor: pointer;
    border: 1px solid transparent;
}

figure > a > img:hover {
    border: 1px solid #e1e4e8;
    box-shadow: 0 0 5px rgba(0,0,0,0.1);
}

figure > a::after {
    content: " 🔍";
    font-size: 0.9em;
    opacity: 0.7;
}

@Charlie-XIAO
Copy link
Contributor
Charlie-XIAO commented Jan 15, 2025
figure > a::after {
    content: " 🔍";
    font-size: 0.9em;
    opacity: 0.7;
}

Well this is actually a good idea: though :after does not work for img it does work for a which I forgot to think about. With something like

figure > a::after {
  content: "Click to see the code that generated this plot";
  display: block;
  font-weight: var(--pst-font-weight-caption);
  margin-top: 0.3rem;
}

we can achieve what @ogrisel wanted:

Normal Hovered over image or caption
Image Image

The rendering is slightly less satisfactory for images that already have a caption though:

Image

@betatim
Copy link
Member
betatim commented Jan 15, 2025

Maybe an option is to re-use some of the styling that hyperlinks have when you hover them. I'm not a huge fan of borders around images but it seems like "similar interaction should look similar" is probably a good principle to follow?

@ogrisel
Copy link
Member
ogrisel commented Jan 15, 2025

Charlie's solution looks good to me.

@ogrisel
Copy link
Member
ogrisel commented Jan 15, 2025

Not sure if changing img borders helps that much. I prefer explicit text.

@ogrisel
Copy link
Member
ogrisel commented Jan 15, 2025

Maybe the ::after text could be shorter, e.g. "[source]" if people prefer.

No strong opinion.

@ArturoAmorQ
Copy link
Member

I would rather do something less repetitive than text in every single image. I don't know if there is an easy way to do it, but I like the idea of a hover border, as it gives the image a button-like feeling.

Another possibility would be a slightly fade or reduced opacity whenever the user hoovers over the image.

@Charlie-XIAO
Copy link
Contributor
Charlie-XIAO commented Jan 15, 2025

Border will cause movement - box shadow is probably what you are looking for.

figure > a:hover > img {
  border-radius: 0.3rem;
  box-shadow: 0 0 0 0.15rem var(--pst-color-secondary);
}

This effect does make explicit that this image is clickable (consistent style with other links) which I like, but IMHO (1) It is still unclear what clicking this image leads to; we can add tooltip, but this might mean some sphinx hack or javascript. (2) Hover effects do not work for mobile devices or tablets, as also mentioned in #30596 (comment).

Light mode Dark mode
Image Image

@ogrisel
Copy link
Member
ogrisel commented Jan 16, 2025

Hover-based hints only is indeed useless on mobile / tablets or with people scrolling while keeping their mouse cursor over the side panel.

I would vote to do both the border / box-shadow thing + the after text.

@betatim
Copy link
Member
betatim commented Jan 16, 2025

I've been trying to google/perplexity.ai for what other websites do or what the recommendations are for letting people know that an image is a hyperlink. But haven't really found anything that is better than what we came up with in this thread :-/ A bit sad given that it seems like we haven't yet found the perfect solution/something everyone really likes

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Projects
None yet
Development

No branches or pull requests

9 participants
0