Talip7/scikit-learn-issues-multilabel huggingface dataset:
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

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

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
I was thinking about using a new CSS rule such as:

```css
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.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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?

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
> 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).

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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).

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
This is the result after adding captions (the first alternative suggested by @Charlie-XIAO):

<img width="1220" alt="Screenshot 2025-01-08 151711" src="https://github.com/user-attachments/assets/0301b1c6-1a98-4823-bf61-10349708b69e" />

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](https://github.com/scikit-learn/scikit-learn/blob/main/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 remind contributors during the creation or review of pull requests.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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:
```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;
}

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
> ```css
> 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

```css
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](https://github.com/user-attachments/assets/72c2da34-aff0-48c3-9fb3-91a63117dc98) | ![Image](https://github.com/user-attachments/assets/ee9365ca-ea73-48c6-8b66-2bcbe8b0e406) |

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

![Image](https://github.com/user-attachments/assets/f20f12fb-2dbe-4158-b08a-c4083db9e3a8)

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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?

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
Charlie's solution looks good to me.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

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

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
Maybe the `::after` text could be shorter, e.g. "[source]" if people prefer.

No strong opinion.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

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

```css
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 https://github.com/scikit-learn/scikit-learn/issues/30596#issuecomment-2577272487.

| Light mode | Dark mode|
|--------|--------|
| ![Image](https://github.com/user-attachments/assets/d79b1b4c-acc8-478c-b0e6-e786a97ad949) | ![Image](https://github.com/user-attachments/assets/97874067-b9fc-418d-9d9d-dfd2096da773) |

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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.

Labels: Documentation
Improve user experience in the user guide - make it clear to users that images are clickable

### 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](https://scikit-learn.org/dev/modules/clustering.html#overview-of-clustering-methods).

### 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

COMMENT:
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

Labels: Documentation
DOC: Example of `train_test_split` with `pandas` DataFrames

### Describe the issue linked to the documentation

Currently, the example [here](https://scikit-learn.org/stable/modules/generated/sklearn.model_selection.train_test_split.html) only illustrates the use case of `train_test_split` for `numpy` arrays. I think an additional example featuring a `pandas` DataFrame would  make this page more beginner-friendly. Would you guys be interested? 

### Suggest a potential alternative/fix

The modification in [`model_selection/_split`](https://github.com/scikit-learn/scikit-learn/blob/d666202a9349893c1bd106cc9ee0ff0a807c7cf3/sklearn/model_selection/_split.py) would be the following:
```
"""
Example: Data are a `numpy` array
--------
>>> Current example

Example: Data are a `pandas` DataFrame
--------
>>> from sklearn import datasets
>>> from sklearn.model_selection import train_test_split
>>> iris = datasets.load_iris(as_frame=True)
>>> X, y = iris['data'], iris['target']
>>> X.head()
   sepal length (cm)  sepal width (cm)  petal length (cm)  petal width (cm)
0                5.1               3.5                1.4               0.2
1                4.9               3.0                1.4               0.2
2                4.7               3.2                1.3               0.2
3                4.6               3.1                1.5               0.2
4                5.0               3.6                1.4               0.2
>>> y.head()
0    0
1    0
2    0
3    0
4    0
>>> X_train, X_test, y_train, y_test = train_test_split(
... X, y, test_size=0.33, random_state=42) # rows will be shuffled
>>> X_train.head()
     sepal length (cm)  sepal width (cm)  petal length (cm)  petal width (cm)
96                 5.7               2.9                4.2               1.3
105                7.6               3.0                6.6               2.1
66                 5.6               3.0                4.5               1.5
0                  5.1               3.5                1.4               0.2
122                7.7               2.8                6.7               2.0
>>> y_train
96     1
105    2
66     1
0      0
122    2
>>> X_test.head()
     sepal length (cm)  sepal width (cm)  petal length (cm)  petal width (cm)
73                 6.1               2.8                4.7               1.2
18                 5.7               3.8                1.7               0.3
118                7.7               2.6                6.9               2.3
78                 6.0               2.9                4.5               1.5
76                 6.8               2.8                4.8               1.4
>>> y_test.head()
73     1
18     0
118    2
78     1
76     1
"""
```

COMMENT:
It sounds like a good idea. I will have a look at the PR.

Labels: Documentation