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

Any plans to support static-site generator websites? #69

Open choldgraf opened 4 years ago

choldgraf commented 4 years ago

Hey there - this is a really neat extension 👍

I saw in the docs that this is currently relying on a server to fetch the snippets before displaying. I think it's possible to fetch and display content from across the web using pure front-end JS, so I am wondering if there's any plan in the future to make this extension work for sites that aren't hosted on readthedocs.

As an example: in my case, I'm working on a tool that lets people publish books with sphinx, and I think this would be an interesting extension to let people use, but they won't be able to host their books on readthedocs currently.

humitos commented 4 years ago

Hi @choldgraf! Thanks for your suggestion.

I've thought about this already and had two ideas to implement this:

  1. Embed all the contents of all the tooltips in the same HTML generated by sphinx.
  2. Make an AJAX request to retrieve the whole content of the target and parse it with JS to get only the content we need.

None of them are trivial and both of them involve increasing the size/load time of each page a lot.

That said, I'm not having the time currently to implement that feature but it's something that I'm not opposed doing in the future. Right now, I'm centered on making the extension more customizable and robust enough to release its first stable version.

Please, share your opinions here or if you already took a look at the code and have an idea about how this could be implemented.

choldgraf commented 4 years ago

Nothing specifically, I just remember looking into this a little while back and seeing lots of examples like this one which I think uses this jquery plugin. It seems a lot of people use JQuery plugins for this kind of thing and embed the preview in an iframe.

tuukkamustonen commented 4 years ago

Just found out this neat little(?) extension. It would be great for .. glossary:: terms.

However, what data is transmitted to RTD site in API calls? I'm hosting company's internal documentation and can't leak any data outside. Standalone site support would be indeed great.

Could it be mentioned on the front page that this is the case - that it now relies on RTD API? Maybe I missed it but at least I couldn't find this information anywhere?

humitos commented 4 years ago

Just found out this neat little(?) extension. It would be great for .. glossary:: terms.

If this refers to :term: role, it does already support it. See #57

However, what data is transmitted to RTD site in API calls? I'm hosting company's internal documentation and can't leak any data outside. Standalone site support would be indeed great.

The documentation must be hosted on Read the Docs.

Could it be mentioned on the front page that this is the case - that it now relies on RTD API? Maybe I missed it but at least I couldn't find this information anywhere?

It's mentioned in the Installation page, at https://sphinx-hoverxref.readthedocs.io/en/latest/installation.html

tuukkamustonen commented 4 years ago

It's mentioned in the Installation page, at https://sphinx-hoverxref.readthedocs.io/en/latest/installation.html

Indeed:

image

I guess I skipped it because it was mentioned in a separate box :) My bad.

jdillard commented 4 years ago

It seems like the JSONHTMLBuilder builder could be used, but only in limited capacity. It would require the user of the extension to use the -b json builder as well, and then maybe a config option that points to where those files were deployed to so they could be loaded with an AJAX request.

humitos commented 2 years ago

In case there is still interest in implementing this feature, this is the code of backend API that handles some special cases --when there is not enough just return the content of the HTML id passed: https://github.com/readthedocs/readthedocs.org/blob/efdb6335b715a38a5b0f5bb9d0fe6cf6771ed145/readthedocs/embed/v3/views.py#L152-L243

I don't think that I personally will work on this anytime soon, but I'm happy to help anyone that wants to do it with the design and reviews if the implementation is not super complex and does not require re-writing the whole extension :)

Otherwise, we can just close the issue and come back to it in the future if we get more people interested in collaborating with it.

chrisjsewell commented 1 year ago

@choldgraf I've done this essentially in https://sphinx-tippy.readthedocs.io, feedback welcome 😄