Add support for `:doc:` role

[humitos]

I think it's not hard to implement showing tooltips on :doc:. Although, this will retrieve the whole page/document and may be "too much" content to be displayed inside the tooltip.

Once the full doc is retrieved, we could cut its content after the first title breaking (h1 or h2, for example).

[astrojuanlu]

+1! I was wondering if this was a misconfiguration on my side, glad that you're tracking it.

[astrojuanlu]

About "too much content", I think sphinx-hoverxref handles this nicely already. See for instance the API tooltip on the poliastro index: https://docs.poliastro.space/en/stable/

It's a {ref} for a whole document, so I could be using {doc} perfectly instead.

Maybe a first iteration loading the whole page and then let people complain? :)

[humitos]

About "too much content", I think sphinx-hoverxref handles this nicely already. See for instance the API tooltip on the poliastro index: docs.poliastro.space/en/stable

This is correct. I think when I opened this issue the modal (which is a completely different js library) was not implemented yet.

Also, we can now make explicit on what roles we want tooltips. So, users can disable on :doc: if they don't want to use a different style (modal), for example.

Once the full doc is retrieved, we could cut its content after the first title breaking (h1 or h2, for example).

I tried to do this at the backend level and I failed --but I was doing a lot of things all together at that time (readthedocs/readthedocs.org#8319 (comment)). Maybe we can give it a try again.

[ericholscher]

@humitos Is this hard to do? I keep wishing we had it, and I'd love to see a simple implementation if it's not a huge pain.

Seems like the main issue is the design decision around how much content to show, and I'm punting for now, and just returning the whole thing. As we said, users can disable this if they want!

[benjaoming]

Does the reader benefit from hoverxref when it will end up showing an entire article? I would argue "yes". It's the right place to start 👍

Once the full doc is retrieved, we could cut its content after the first title breaking (h1 or h2, for example).

To mature the feature, it would be great to be able to define an excerpt and an "Open ↕️" button. After all, there is no point in making the reader read an entire documentation article in a popup tooltip. The tooltip is there to give some additional context to a concept from another article, but should be enough to show just the first 1-3 paragraphs/block elements.

Small tweak can also be to see if the work from #227 will help improve page load experience.

[humitos]

@ericholscher I don't think it should be hard to do the simple version: "Return all the page".

I'm adding this issue to the roadmap in Q1, so we prioritize it soon.

[ericholscher]

The new implementation will likely change this design, so holding off on this 👍