Install the package

pip install --pre sphinx-hoverxref

Once we have the package installed, we have to configure it on our Sphinx documentation. To do this, add this extension to your Sphinx’s extensions in the file.

extensions = [
     # ... other extensions here

After installing the package and adding the extension in the file, you can use :hoverxref: role to show a tooltip 1 when hovering with the mouse.


This extension requires a backend server to retrieve the tooltip content. Currently only Read the Docs is supported, so it will only work if your documentation is hosted on Read the Docs.

If you prefer to apply this behavior to all your :ref: in your documentation, you can use the config hoverxref_auto_ref.

See Usage for more use cases and Configuration for a full list of available configs.


we use tooltips as a generic word, but we refer to both, tooltips and modal dialogues