sphinx-hoverxref

1.4.2 verified Fri May 01 auth: no python

A Sphinx extension that shows tooltips with embedded content when hovering over cross-references. Current version is 1.4.2 (2024-04-24). Release cadence is irregular, with occasional minor updates.

pip install sphinx-hoverxref

Common errors

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

cause Wrong import path in conf.py extensions list.

fix

Use 'sphinx_hoverxref.hoverxref' instead of 'hoverxref'.

error NameError: name 'hoverxref_roles' is not defined ↓

cause Trying to use hoverxref_roles variable before assignment or without proper configuration.

fix

Define hoverxref_roles as a list in conf.py after extensions are loaded.

Warnings

breaking Version 1.0.0 changed the import path from 'hoverxref' to 'sphinx_hoverxref.hoverxref'. Old configs using extensions = ['hoverxref'] will fail. ↓

fix Use extensions = ['sphinx_hoverxref.hoverxref'] instead.

gotcha The extension requires Sphinx >= 1.8. Using an older Sphinx version may cause cryptic errors. ↓

fix Upgrade Sphinx to at least 1.8.

gotcha Tooltips may not appear if the role is not explicitly configured via hoverxref_roles. By default, no roles are enabled. ↓

fix Add hoverxref_roles = ['any'] or specify roles like ['class', 'func'].

Imports

hoverxref_extension
wrong
```
extensions = ['hoverxref']
```
correct
```
extensions = ['sphinx_hoverxref.hoverxref']
```
Wrong import causes extension not found error.
hoverxref_roles
```
from sphinx_hoverxref import hoverxref_roles
```
Used to add custom roles if needed.

Quickstart

Enable hoverxref in your Sphinx conf.py. The extension must be added as 'sphinx_hoverxref.hoverxref' (not 'hoverxref').

# conf.py
extensions = ['sphinx_hoverxref.hoverxref']

# Enable tooltip for all roles
hoverxref_roles = ['any']

# Optional: set tooltip width
hoverxref_tooltip_width = 300