This extension defines a custom role called
When this role is used, it will show a tooltip 1 when the
hover mouse event is triggered,
and will embed the content of the document/section the link is pointing to, into the tooltip’s content.
:hoverxref: role uses Sphinx’s internals reference resolution to find out where the link points to.
So, the way of referencing the section works in the same way as the
:ref: standard role.
See Sphinx’s ref role documentation for more information.
Simplest usage example,
This will :hoverxref:`show a tooltip <hoverxref:hoverxref>` in the linked words to ``hoverxref``.
will render to this:
This will show a tooltip in the linked words to
Tooltip on intersphinx content¶
Sphinx comes with a nice built-in extension called sphinx.ext.intersphinx that allows you to generate links to specific objects in other project’s documentation pages.
You can combine this extension with
sphinx-hoverxref to show tooltips over these links to other projects.
For example, this documentation itself configures intersphinx with Read the Docs documentation and allow us
to do the following:
Show a tooltip for :doc:`Read the Docs automation rules <readthedocs:automation-rules>`.
That will render to:
Show a tooltip for Read the Docs automation rules.
Keep in mind that the linked project should be hosted at Read the Docs. This is a limitation that will be removed in the future.
Tooltip on custom object¶
Sphinx has the ability to define custom objects (via Sphinx.add_object_type).
hoverxref can also show a tooltip on these objects if desired.
You need to tell
hoverxref which are the roles where the tooltip has to appear on.
To do this, use
This documentation defines the
The role is used to define all the configurations of the extension.
These configurations are added to the Sphinx index and we can easily refer to them and show a tooltip.
This is reStructuredText code to do this:
Show a tooltip to :confval:`hoverxref_auto_ref <hoverxref_auto_ref>` configuration.
the previous code will render to:
Show a tooltip to
Tooltip on all :ref: roles¶
If you want to show a tooltip in all the appearances of the
you have to set the configuration
hoverxref_auto_ref = True in your
After setting that config, using
:ref: will just render the tooltip:
Show a tooltip to :ref:`usage:Tooltip on all :ref: roles` section on this page.
that reStructuredText code will render to:
Show a tooltip to Tooltip on all :ref: roles page.
Tooltip on Sphinx Domains¶
You can decide whether use
hoverxref on a particular Sphinx Domain as well.
An example using Python Domain would be like:
That will render to:
hoverxref on a domain, you need to use the config
indicating which are the domains you desire.
Tooltip with content that needs extra rendering steps¶
hoverxref supports including arbitrary HTML,
you may find that it could be possible that there are some content that it’s not well rendered inside the tooltip.
If this is the case, it may be because there are some extra actions that needs to be done after the content is injected in the tooltip.
Note that Sphinx>3.5 adds a feature to only include JS/CSS in pages where they are used instead of in all the pages. This may affect the rendering of tooltips that includes content requiring extra rendering steps. Make sure you are using Sphinx 3.4.x or >=4.1.x if you require rendering this type of content in your tooltips.
To render a tooltip with a
sphinx-tabs content you need to enable
Show a :ref:`tooltip with Sphinx Tabs <installation:Installation>` on its content.
Show a tooltip with Sphinx Tabs on its content.
To render a tooltip where its contents has a
mathjax you need to enable
Show a :hoverxref:`tooltip with Mathjax <mathjax:Mathjax>` formulas.
Show a tooltip with Mathjax formulas.
we use tooltips as a generic word, but we refer to both, tooltips and modal dialogues