How can tooltips be stylized to show that they are tooltips?

[dsandber]

A user might assume that the tooltips (which look like links) are links and thus not try to hover over them. Is there a way to clearly show they are tooltips so the user is motivated to hover if they are interested?

I looked into what the conventions are, and it seems the two most popular are a dotted underline like some browsers show the "abbr" element:

https://developer.mozilla.org/en-US/docs/Web/HTML/Element/abbr

And a info icon:

https://ux.stackexchange.com/questions/101133/is-it-better-to-use-i-or-for-tooltip-help-content-on-mobile

Can sphinx-hoverxref support either of these? How?

Thanks!

[humitos]

We have some conversation about this at #11

A user might assume that the tooltips (which look like links) are links and thus not try to hover over them.

Currently, tooltips use a dotted underline similar to abbr elements to be differentiated from regular links.

Is there a way to clearly show they are tooltips so the user is motivated to hover if they are interested?

You can expand the CSS class .hoverxref in your documentation to make them look as you prefer. If you come up with a nicer look and feel I'd appreciate it if you share your settings 😃

a info icon:

This was already considered in #11. However, hovering on Mobile does not work great, so I think we didn't add it. See #5

[dsandber]

Oh, somehow I missed that the underlining was already there! Great, thanks.

Re: info icon + mobile, I noticed that right now clicking on the hover-link (instead of hovering) bring you to a new page. Is there a way to disable this? On mobile, clicking could be used to bring up the hover-box rather than going to a new page. Then the icon would work fine on mobile, no?

[humitos]

Is there a way to disable this?

No, there is no way to disable this currently.

On mobile, clicking could be used to bring up the hover-box rather than going to a new page.

That would be a confusing UX to me. You will have to tap twice to enter the link.

Then the icon would work fine on mobile, no?

I'm not sure. I think it doesn't really make sense to show a tooltip on mobile since the screen is too small that the tooltip would be hard to read anyways. We should probably disable it automatically if we detect we are on mobile.

[dsandber]

Yeah, I was assuming there's no way to click the link.

I think I'm coming from a different assumption about the use case than you -- I'm assuming the hover link is there to provide a bit of extra information about what a word/concept means, not to link to a whole other big API page.

In the "hover-links are short" world-view, it's more reasonable to pre-load them and to show them when clicked on mobile.

Reasonable behavior when short:

• Preload
• On mobile: Show on click, never replace page with it
• On non-mobile: Show on hover or click, never replace page with it

Reasonable behavior when long:

• Don't preload
• On mobile: Replace with click
• On non-mobile: Show on hover, replace with click

Maybe an attribute could be added that would support both these uses?

[humitos]

Yeah, I was assuming there's no way to click the link.

The hoverxref extension only triggers the tooltip on hover. If you click the link, it works as a regular link: opens a new page.

I think I'm coming from a different assumption about the use case than you -- I'm assuming the hover link is there to provide a bit of extra information about what a word/concept means, not to link to a whole other big API page.
In the "hover-links are short" world-view, it's more reasonable to pre-load them and to show them when clicked on mobile.

This depends on the documentation set and the author. Some people will use this to show a small context, and some authors will show enough context that may not be "small". In fact, we support a "modal tooltip" to show bigger pages.

I don't think we can make this assumption in a general way that works for everybody. The extension currently supports both scenarios: small and big content.

Preload

This issue is about styling the tooltip, not preloading its content. We are discussing pre-loading at #127 and I don't think it's related to this issue.

On mobile: Show on click, never replace page with it

For mobile, we have #5 open already. We can keep the discussion there, but I think the correct approach there is to disable tooltips on mobile since the screen is too small.

[humitos]

Hi! Is there anything else here to talk about? Otherwise, I'll close the issue.

[dsandber]

My point was that there are some common cases that relate to these different tickets and that perhaps should be handled with a common attribute.

I'll close the ticket.