search

readthedocs / sphinx-hoverxref

Sphinx extension to show tooltips with content embedded when hover a reference.
https://sphinx-hoverxref.readthedocs.io/
MIT License
95 stars 41 forks source link

Local testing? #112

Open leotrs opened 3 years ago

leotrs commented 3 years ago

The documentation says this needs a backend server such as RTD. Is there a way of testing this locally? Thanks

stsewd commented 3 years ago

You can set the hoverxref_project and hoverxref_version settings in your conf.py file. Of course, you would need to have a that project and version on RTD, and it would embed the content from the version hosted on RTD, not from your local changes.

humitos commented 3 years ago

@leotrs are you trying to test the extension to collaborate as a developer? If this is the case, you can take a look at https://sphinx-hoverxref.readthedocs.io/en/latest/development.html

or are you trying to test the extension as a user to see how it looks like? If this is the case, you can import your project on Read the Docs and enable Pull Request build, open a PR that install the extension and check out how it looks.

leotrs commented 3 years ago

@humitos thanks for the answer - for now I was interested in local testing as a user. Looking forward to maybe contributing in the future!

stsewd commented 3 years ago

@leotrs you can use my solution https://github.com/readthedocs/sphinx-hoverxref/issues/112#issuecomment-807172548 or the suggestion from @humitos. Let us know if you have more questions.

astrojuanlu commented 2 years ago

or are you trying to test the extension as a user to see how it looks like? If this is the case, you can import your project on Read the Docs and enable Pull Request build, open a PR that install the extension and check out how it looks.

This requirement is a bit too demanding for some use cases and makes any local development workflow incomplete. Would you consider reopening this issue until there's a more lightweight way to test the extension locally in a way that the RTD PR builder is not needed?

Unfortunately, we're dropping this extension in https://github.com/orchest/orchest/pull/1202 mainly because of this.

cc @ricklamers

humitos commented 2 years ago

@astrojuanlu reading the feedback from that PR, the only mention to hoverxref I found is the following:

Feedback: too easy to accidentally trigger opening a popup and too difficult to test locally (it appears as broken without warning)

  1. what would be a good way to reduce the accidental triggering of a popup without compromising the UX?
  2. would it be enough to update the message from just "Loading ..." to "The content can't be loaded unless running on Read the Docs" or similar? (related to #132 and #17)

Are there any other feedback that you could share with us that maybe is not written in that PR description/comments?

Note the extension requires a backend server, so it won't work at all when reading the docs locally. All the suggestions and/or alternatives that we have commented in this issue and under the "Development" section of the docs are workarounds to have a preview of it. However, it's not 100% accurate for different reasons. The most noticeable being "loading outdated content into the tooltip" because the server has an older version of it compared with the local version. That said, even if we find a way to easily allow to test it locally, it could confuse users in a deeper and hard to understand way.

I'm open to suggestions, and I'd appreciate your feedback on this. Thanks 🙏🏼

astrojuanlu commented 2 years ago

Thanks @humitos for taking it into consideration!

Are there any other feedback that you could share with us that maybe is not written in that PR description/comments?

It's basically the two points I raised there.

  1. the only way that comes to mind to reduce the accidental triggering would be a time delay (maybe ~1 second or so, possibly configurable) to trigger the request. there might be other, more creative solutions. I also have no idea what accessibility guidelines are there around this kind of behavior in general.
  2. if I understand correctly, the embed logic is more or less self-contained here https://github.com/readthedocs/readthedocs.org/blob/579ac3b15/readthedocs/embed/v3/views.py wondering if the whole rtd development installation should be needed (I get it's needed now with the current architecture though). having a better error message would be a much-needed step forward indeed, although it wouldn't help recreating the documentation locally as a user would see it.
wRAR commented 5 months ago

Related but I think ideologically different issue: docs built without RTD and not deployed there, such as ones built locally or ones built for shipping in various distro packages, cannot display popups, but still make a request to the RTD API, so it would be very nice to just disable making the request in those cases. Is there an easy way for that (maybe as something passed to sphinx-build)? If not, can it be added?

humitos commented 5 months ago

cannot display popups, but still make a request to the RTD API, so it would be very nice to just disable making the request in those cases. Is there an easy way for that (maybe as something passed to sphinx-build)? If not, can it be added?

@wRAR when building on Read the Docs, an environment variable READTHEDOCS=True is defined (https://docs.readthedocs.io/en/stable/reference/environment-variables.html), so that could be used in the Sphinx process to disable this extension if that variable is not defined.