readthedocs / sphinx-hoverxref

Sphinx extension to show tooltips with content embedded when hover a reference.

sphinx-hoverxref

sphinx-hoverxref is a Sphinx extension to add tooltips on the cross references of the documentation with the content of the linked section.

Example

Installation

You can install sphinx-hoverxref from PyPI:

pip install sphinx-hoverxref

Or, alternatively, install it from GitHub directly (requires git):

pip install git+https://github.com/readthedocs/sphinx-hoverxref

Configuration

Add this extension in your conf.py file as:

extensions = [
 # ... other extensions here

 'hoverxref.extension',
]

Documentation

Check out the full documentation at https://sphinx-hoverxref.readthedocs.io/

sphinx-hoverxref's Issues

Tooltipster adds vertical bars when rendering the second time

The first time the Tooltipster loads, it looks like:

then, all the following times:

Add option to only enable hover content on :hoverref: and :glossary:

Similar to hoverxref_auto_ref but with hoverxref_auto_glossary

New tooltip style suggestion

Would be great to have such kind of tooltips as on this page:
https://help.apple.com/xcode/mac/current/#/dev84c38774c

Modal and Tooltip in the same docs

After merging #39 we will have support for a new type: modal dialogues.

While developing it, I found that they are really good to embed whole documents or big sections, while tooltips would be more useful to show something small quickly in the page.

It would be good to be able to decide when to show which one:

• new roles: :hoverxrefmodal: and :hoverxreftooltip:
• accept hoverxref_type='both'
• new config hoverxref_default_type to default to a specific type if :hoverxref: is used, and also when hoverxref_auto_ref=True is used
• make a decision dynamically based on the amount of content
  • use tooltips for small content that will give a context to what's the user is reading
  • use modals when the content is larger and may contain a whole document or section

Create a `:hoverxref:` role

Create a totally different :hoverxref: role and add a config to disable rendering tooltips on regular :ref:.

This way, the user can have more control over where to add a tooltip or not.

Formatting of tooltip contents?

First of all, thanks for a great extension :) It's really useful. I'm having trouble with the formatting of the popup - please see shots below.

1. Whenever we have a table included in the popup, its columns get wrapped (which is nice), but the linespacing is messed up?
   

2. Is there a way to format the heading so it remains the same (or larger?) than the tooltip contents? In the image below the link text "A CellML identifier:" is smaller than the other points? Neither have any special formatting.
   

Thanks in advance for any thoughts - I'm not sure whether these are bugs or whether I've done something wrong somewhere!

Relative links in popup are broken/wrong

When loading the content of another section, if there are relative links (e.g. href="#section-name"), they will break --or point to the wrong place, when clicking on them because we are not in the page where the link was rendered.

To make these links to work, they need to be re-written somewhere (server or client) to point to the right document.

Add compatibility with Mathjax3

See https://frc-docs--639.org.readthedocs.build/en/639/docs/software/advanced-controls/state-space/state-space-intro.html#wpilib-s-linearsystemloop

`:term:` tooltip problems with terms that share definitions

As others have said, thanks for the extension! It has made a huge difference in the usefulness of my documentation.

I have the following problem:

I have a glossary page with lots of entries like this:

.. glossary::
  
   term 1
   term 2
      definition for both term 1 and term 2

I have hoverxref setup to show tooltips for terms, However, :term:`Term 1` brings up a tooltip that just says "term 2" and doesn't include the definition. Is there a way around this?

Thanks again!

Typlog theme seems to be not compatible

Theme error:
An error happened in rendering the page 404.
Reason: UndefinedError("'metatags' is undefined")

Theme URL: https://sphinx-typlog-theme.readthedocs.io/

Send `nparagraphs=` to the backend to cut the content response

Add a config hoverxref_paragraphs= to configure how many paragraphs should be included in the response from the backend.

Errors when trying to "make html"

I receive this error when try to "make html"

Extension error:
Could not import extension hoverxref.extension (exception: No module named 'hoverxref')
make: *** [html] Error 2

Where should the "hoverxref" folder be? should it be a sibling or child of the "docs" folder?

Thanks a lot!

Local testing?

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

Any plans to support static-site generator websites?

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.

Issue with hover content not showing up

https://daltz-private.readthedocs.io/en/glossary/docs/software/advanced-controls/introduction/introduction-to-pid.html

with the relative conf.py here
https://github.com/Daltz333/frc-docs/blob/glossary/source/conf.py

Move from overridden domains to a custom role

Instead of using a custom role, this extension is using overrides on domains, which is going to introduce problems with reference resolution as Sphinx has multiple Python and Standard domains.

Couldn't this instead implement our own custom role, instead of repurposing XRefRole and having to catch reference resolution in every domain?
https://github.com/readthedocs/sphinx-hoverxref/blob/master/hoverxref/extension.py#L176-L184

Add support for `:doc:` role

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

Make links with tooltip visually different

It would be good to make these links visually different from a regular link that won't show a tooltip.

It may be a small icon, or maybe some CSS style.

I was thinking on using the same style as :abbr:, that adds a small dotted border at the bottom as the first approach.

Broken on PR builds

Currently hover content just shows the following image on PR builds.

Offender: https://frc-docs--674.org.readthedocs.build/en/674/docs/software/advanced-controls/introduction/introduction-to-pid.html

Embed any block of content into the tooltip

Now the tooltip includes everything in the doc or section that you specify. But what if you want some specific paragraph, or two, or a paragraph and a list, or whatever. It should be possible to mark up any content chunk with some kind of id and embed it into the tooltip.

Add a config to ignore specific references

There are some known references that do not work currently (genindex and py-modindex for example). There may be more...

I noted this on Scrapy docs: https://docs.scrapy.org/en/latest/

It would be good to have a config like hoverxref_ignore_ref = ['genindex', 'py-modindex'] (by default), where the user can add some custom references to ignore as well.

References in that list will be ignored by hoverxref and won't add any tooltip there, avoiding showing a broken tooltip (Loading...) and/or an incredible big tooltip that does not make sense at all.

Support intersphinx

Currently hoverxref_project and hoverxref_version are used globally and there is no way to specify to get the content from another different project.

See https://www.sphinx-doc.org/en/master/usage/extensions/intersphinx.html

Installation documentation should mention hoverxref_auto_ref = True

https://sphinx-hoverxref.readthedocs.io/en/latest/installation.html says:

After installing the package and adding the extension in the conf.py file, all the :ref: roles will show a tooltip when hovering with the mouse.

But this is wrong. You have to set hoverxref_auto_ref = True for this to work. The page should mention this, since I suspect this will be desired by most. Alternately, I would suggest making True the default for this option.

Turn instructions into a numbered procedure

The instructions should be numbered, so the user can see exactly where they are and what step is next.
For example:

Install the package.
To configure the package on our Sphinx documentation, in the ''conf.py" file, add the extension to the Sphinx's extensions.
etc.
In this case you can get rid of the unnecessary text where you repeat yourself.

Developer docs

Update them with,

• Mention the usage of make livehtml
• Point users to the new docker setup for read the docs

Consider adding the sphinx-extension GitHub topic

Just wanted to say you should consider adding the sphinx-extension topic, https://github.com/topics/sphinx-extension, to the repo so it is easier for others to find on the GitHub ecosystem. There are currently 88 other sphinx extensions that use that topic.

Migrate to CircleCI

We are moving everything to CircleCI, so we should move this project as well.

See readthedocs/sphinx-notfound-page#130

Be sure to keep the tests on all the Sphinx minor versions.

Tooltip on sidebar

It may be interesting to be able to hover on the sidebar and get the first paragraph of the content referenced.

• Requires a change in the backend to let it know to return chunked content and not the whole section
• Would be good to make the amount of content configurable via a hoverxref_ config that is sent to the backend

Support Sphinx Domains in a general way

Currently, we support Python Domain. Although, it would be good to make it work with other internal Domains and also be able to support 3rd party domains, as readthedocs/readthedocs.org#6087 (comment) for example.

Related to #14

Issue with with Sphinx 3.0.0

Hi, we have a project that makes use of sphinx-hoverxref and it builds fine using Sphinx 2.4.0, but not with Sphinx 3.0.0. Here is what we are getting when doing make html (here is the corresponding log):

sphinx-build -b html -d build/doctrees   src build/html
Running Sphinx v3.0.0
making output directory... done

Exception occurred:
  File "/Users/Alan/virtualenv/cellml-specification/lib/python3.7/site-packages/hoverxref/extension.py", line 198, in setup_sphinx_tabs
    for listener_id, function in app.events.listeners.get('html-page-context').items():
AttributeError: 'list' object has no attribute 'items'
The full traceback has been saved in /var/folders/k8/gmbwgb910z52mrztjsdwjpbh0000gn/T/sphinx-err-v2lr0bjq.log, if you want to report the issue to the developers.
Please also report this if it was a user error, so that a better error message can be provided next time.
A bug report can be filed in the tracker at <https://github.com/sphinx-doc/sphinx/issues>. Thanks!
make: *** [html] Error 2

Anyway to support tooltips for internal references created by numref?

Thanks for a great wee tool :)

I'm having trouble combining the numref role with tooltips - does it perhaps need another round of rendering in the same way that mathjax panels do? My conf.py file looks like this:

hoverxref_auto_ref = True
hoverxref_roles = ['ref', 'numref']
hoverxref_role_types = {
    'ref': 'tooltip',       
    'numref': 'tooltip',    
}

The pages are working fine for things which use the ref role, just not the numref one.

Readthedocs site is here: https://cellml-specification-dev.readthedocs.io/en/i314_numref_hoverxref/reference/formal_and_informative/specB09.html

If you have any suggestions I'd be very glad to hear them. Thanks!

Design tooltip

There are some ideas already implemented in MediaWiki and GitHub from where we can base ours:

• https://meta.wikimedia.org/wiki/WMDE_Technical_Wishes/ReferencePreviews
• https://www.mediawiki.org/wiki/Page_Previews
• https://github.com/Justineo/github-hovercard

We are using this jQuery extension to render the tooltip: https://iamceege.github.io/tooltipster/ so, maybe a theme of it can be created or just adding an extra CSS file it's enough.

The first step for this issue is to create a design document explaining what content should be included in the tooltip, considering the possibilities of having different tooltips type (as GitHub does for PR, issues, user cards, etc) and showing mock examples of they would look like.

This document will help us to know if we need to change something in the API backend or the data that we are getting right now is enough.

We probably can have two instances of this design/implementation:

1. make it work with what we have already to look nice, but not perfect
2. grow from there expanding the design and modifying the backend

A help guide about how to write this document, could be this one: https://www.freecodecamp.org/news/how-to-write-a-good-software-design-document-66fcf019569c/

Add glossery/term support.

This would be incredibly useful for this kind of situation.

"Who is using this extension?" documentation section

Consider adding a documentation page mentioning people using this extension:

• Scrapy: https://scrapy.org/doc/
• Hypothesis: https://hypothesis.readthedocs.io/
• returns: https://returns.readthedocs.io/
• poliastro: https://docs.poliastro.space/
• etc

OrderedDict mutation error

  File "/home/docs/checkouts/readthedocs.org/user_builds/docs/envs/6080/lib/python3.7/site-packages/hoverxref/extension.py", line 198, in setup_sphinx_tabs
    for listener_id, function in app.events.listeners.get('html-page-context').items():
RuntimeError: OrderedDict mutated during iteration

See https://readthedocs.org/projects/docs/builds/9551545/

Better xref resolve

I think I'm manually resolving URLs. This object could be useful.

https://www.sphinx-doc.org/en/master/extdev/domainapi.html#sphinx.domains.Domain.resolve_xref

Add link to Sphinx ref roles documentation

Since the hoverxref is based on the ref role, it would be helpful to provide a link to the documentation: https://www.sphinx-doc.org/en/master/usage/restructuredtext/roles.html?highlight=role#cross-referencing-arbitrary-locations
For example, in the index page tip section.

Override domains and translator only in HTML output

We need to override the Domains and Translators only when building app.builder.format == 'html', otherwise it makes no sense and it could produce issues.

Reference: CEED/libCEED#506 (comment)

Make it work with/without `autosectionlabel` extension

Without using this extension and particular setting, the user can just write

:ref:`My title <A section somewhere>`

note that there is no : to separate the name file and the section.

and it should work.

https://www.sphinx-doc.org/en/master/usage/extensions/autosectionlabel.html#confval-autosectionlabel_prefix_document

Build failed in readthedocs

Hi,
We can successfully install and build our project using this extension locally (make html). But when we push the code to GitHub, it triggers an automatic build in readthedocs (webhook) and this build fails with the error:

Extension error:
Could not import extension hoverxref.extension (exception: No module named 'hoverxref')

Are we missing some configuration in readthedocs? The readthedocs failed build log is attached below:
Build log.txt

This is our project in GitHub. To pass the build in readthedocs, we have temporarily commented out this extension in our conf.py file.

Trigger `:hover` event on mobile

Triggering the :hover event on Mobile is not well supported and it's not recommended. So, in case we want to support this we need to find a different approach.

One idea that I got from Twitter was to detect that the reader is on mobile and if so, add a small icon that when you click it, it triggers the event and shows the tooltip.

I'm not sure if it worth the implementation effort since mobile is not widely used to read documentation but also because the tooltip will be too small probably and hard to read its content. Some experimenting could help to make a better decision here.

Comptability with `sphinx-tabs==2.x`

This Javascript line,

https://github.com/humitos/sphinx-hoverxref/blob/e0df0757a2ddffe2ade29462718d9e54d8583924/hoverxref/_static/js/hoverxref.js_t#L42

fails because in sphinx-tabs==2.x the file is _static/tabs.js.

Support sphinxcontrib-bibtex

It would be quite useful if this plugin could be used to support sphinxcontrib-bibtex on top of other Sphinx references. That way you could hover over a citation, and get a read-out of the content that the citation points to.

Improve logging

There are some issues around logging that can be improved,

1. Warning seems to be "too aggressive" in the Sphinx content. People uses a lot -W when building their docs on CI systems. This means that their builds fails because hoverxref logs some warnings.
2. Warning on hoverxref not fully configurated, may be better as INFO as well. Otherwise, people need to force the definition of it in their conf.py --when the extension only works on Read the Docs and this is automatically configured.
3. A lot of log.info is thrown in the output mentioning the data that was injected. This is useful when debugging only, so it may be good to change to that level.
4. Usage of default role it's better candidate for an info (at this line). We already have a config that sets the default role.

I'm not super happy introducing these warning changes in the latest release because it broke some users builds. However, they seem to be good warnings by default, so the first time you install the extension you are able to configure it completely.

References: scrapy/scrapy#4480

Remove `dl` and `dt` node manipulation

This is covered in the server itself at https://github.com/readthedocs/readthedocs-ext/pull/251

Handle AJAX API call error

If the call to the API fails, the tooltip show "Loading...". It may be good to show a message like "It was not possible to load the content." or similar to have a better feedback to the user.

Clarify Read the Docs configs

I just realized that these three configs (hoverxref_project, hoverxref_version and hoverxref_api_host) are confusing for users, and we should probably add a note that they should not be modified.

https://sphinx-hoverxref.readthedocs.io/en/latest/configuration.html#confval-hoverxref_api_host

People is modifying them because their CI starts failing saying they are not defined and they have fail on warnings enabled. So, defining them makes the CI happy but breaks all the tooltips on RTD.

It may be good to explain this case and suggest the users to define the environment variables READTHEDOCS_PROJECT and READTHEDOCS_VERSION in their CI to avoid it failing in case they are using -W.

Reference: scrapy/scrapy#4480 (comment)

Incompatible with Sphinx 3.0

Sphinx 3.0 was released two hours ago, and we noticed in our pipelines this error coming from sphinx-hoverxref:

Traceback (most recent call last):
  File "/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/sphinx/cmd/build.py", line 276, in build_main
    app = Sphinx(args.sourcedir, args.confdir, args.outputdir,
  File "/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/sphinx/application.py", line 268, in __init__
    self.events.emit('config-inited', self.config)
  File "/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/sphinx/events.py", line 107, in emit
    results.append(listener.handler(self.app, *args))
  File "/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/hoverxref/extension.py", line 79, in setup_sphinx_tabs
    listeners = list(app.events.listeners.get('html-page-context').items())
AttributeError: 'list' object has no attribute 'items'

Exception occurred:
  File "/home/vsts/work/1/s/.tox/docs/lib/python3.8/site-packages/hoverxref/extension.py", line 79, in setup_sphinx_tabs
    listeners = list(app.events.listeners.get('html-page-context').items())
AttributeError: 'list' object has no attribute 'items'

By the way, thanks for this wonderful extension ✨

Glossary terms in hover content lead to 404

https://daltz-private.readthedocs.io/en/glossary/docs/software/advanced-controls/introduction/introduction-to-pid.html

More permissive config on re-build

Most of the configs are currently defined as they affect env, but some of them are safe to be moved to html and avoid a full-rebuild when they are changed.