Add custom embed views for intersphinx

[ericholscher]

We have the embed tooling, and intersphinx. It would be cool to build a basic UI that would do an embed on hover for intersphinx links. This would allow folks to see the referenced documentation inline, without having to click out.

[stsewd]

Related to #1758

[ericholscher]

GitHub now does this on issue/PR hover, which is a great implementation of it.

[ericholscher]

Wikipedia also does a version of this.

[ericholscher]

More details of the Wikipedia version: https://www.mediawiki.org/wiki/Page_Previews

[stale]

This issue has been automatically marked as stale because it has not had recent activity. It will be closed if no further activity occurs. Thank you for your contributions.

[ericholscher]

Still working on this, need to finish it up :)

[humitos]

I've been thinking a little more about this and how to emulate the Github behavior in our docs: when you hover an issue number in a Github conversation it shows a small popup with some useful information about it

I think we could do something similar in a separate Sphinx extension (outside our core repository) without any change in our current source code. My idea is to override the ref Sphinx role to add a Javascript hover event and some data- attributes to the anchor link.

Example

The author writes,

:ref:`how to migrate from v1 <config-file/v2:Migrating from v1>`.

and the HTML rendered is,

<a class="reference internal" 
   href="v2.html#migrating-from-v1"
   data-project="docs"
   data-version="stable"
   data-doc="config-file/v2"
   data-section='Migrating from v1">
  <span class="std std-ref">how to migrate from v1</span>
</a> 

data-project and data-version could be got from a global setting since it will be the same for all the links.

with a Javascript event linked to an API call for,

https://readthedocs.org/api/v1/embed/?project=docs&version=stable&doc=config-file/v2&section=Migrating%20from%20v1

[ericholscher]

Yea, I don't think we need much new backend code, just frontend/JS.

[humitos]

I started writing this extension at https://github.com/humitos/sphinx-hoverxref

There is a first implementation for the Python side of the extension already done that adds the attributes to the <a> tags that are mentioned in the previous comment. There are some things that can be added to be more configurable, though.

Front-end part is coming soon, but I will probably need some help to make it work nicely.

[humitos]

I'm closing this issue.

We have the extension built already and a beta release was published. There is no big known issues currently.

In any case, we can track these problems on its own repository: https://github.com/readthedocs/sphinx-hoverxref