Skip to content
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

Add support for :doc: role #18

Open
humitos opened this issue Aug 22, 2019 · 7 comments
Open

Add support for :doc: role #18

humitos opened this issue Aug 22, 2019 · 7 comments
Labels
Feature New feature

Comments

@humitos
Copy link
Member

humitos commented Aug 22, 2019

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

@humitos humitos added the Feature New feature label Aug 22, 2019
@astrojuanlu
Copy link
Contributor

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

@astrojuanlu
Copy link
Contributor

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/

Screenshot 2021-11-25 at 09-13-01 poliastro - Astrodynamics in Python — poliastro 0 15 2 documentation

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
Copy link
Member Author

humitos commented Nov 25, 2021

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
Copy link
Member

ericholscher commented Feb 22, 2023

@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
Copy link
Contributor

benjaoming commented Feb 23, 2023

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
Copy link
Member Author

humitos commented Feb 23, 2023

@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
Copy link
Member

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

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

No branches or pull requests

5 participants
@ericholscher @humitos @astrojuanlu @benjaoming and others