Local testing?

[leotrs]

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

[stsewd]

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]

@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]

@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]

@leotrs you can use my solution #112 (comment) or the suggestion from @humitos. Let us know if you have more questions.

[astrojuanlu]

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 orchest/orchest#1202 mainly because of this.

cc @ricklamers

[humitos]

@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 Nicer error when the request produces 404 #132 and Handle AJAX API call error #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]

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]

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]

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.