Configuration

The default settings should be enough for most of the cases. For more specific use cases, you can customize these configuration options in your conf.py file.

General settings

These settings are global and have effect on both, tooltips and modal dialogues.

hoverxref_role_types

Description: Style to use by default when hover each type of reference (role).

Default: {}

Type: dictionary

Example:

{
    'hoverxref': 'modal',
    'ref': 'modal',  # for hoverxref_auto_ref config
    'confval': 'tooltip',  # for custom object
    'mod': 'tooltip',  # for Python Sphinx Domain
    'class': 'tooltip',  # for Python Sphinx Domain
}

hoverxref_default_type

Description: Default style when the specific one was not found in hoverxref_role_types.

Default: tooltip

Options: tooltip or modal

Type: string

hoverxref_auto_ref

Description: Make all :ref: role to show a tooltip.

Default: False

Type: bool

hoverxref_ignore_refs

Description: Ignore to add tooltip on specific references. Useful when using hoverxref_auto_ref

Default: ['genindex', 'modindex', 'search']

Type: list

hoverxref_domains

Description: List containing the Sphinx Domain’s names where hoverxref has to be applied.

Default: []

Type: list

hoverxref_roles

Description: List containing roles where hoverxref has to be applied.

Default: []

Type: list

Example:

hoverxref_roles = [
    'numref',
    'confval',
    'setting',
]

hoverxref_intersphinx

Description: Enable Sphinx’s hoverxref extension on intersphinx targets from intersphinx_mapping.

Default: []

Type: list

Warning

The Sphinx’s target project must be hosted on Read the Docs to work or, be one of the allowed external projects: currently CPython, SymPy, NumPy are supported.

hoverxref_intersphinx_types

Description: Style used for intersphinx links.

Default: {}. It uses hoverxref_default_type if the intersphinx target is not defined in this config.

Type: dict

Example:

{
    # make specific links to use a particular tooltip type
    'readthdocs': {
        'doc': 'modal',
        'ref': 'tooltip',
    },
    'python': {
        'class': 'modal',
        'ref':, 'tooltip',
    },

    # make all links for Sphinx to be ``tooltip``
    'sphinx': 'tooltip',
}

hoverxref_sphinxtabs

Description: Trigger an extra step to render tooltips where its content has a Sphinx Tabs

Default: False

Type: bool

hoverxref_mathjax

Description: Trigger an extra step to render tooltips where its content has a Mathjax

Default: False

Type: bool

hoverxref_api_host

Description: Host or root URL for the API to retrieve the content of the floating window

Warning

You shouldn’t modify this setting unless you know what you are doing. Its default should be fine to build the documentation and make it work in Read the Docs.

Default: /_

Type: string

Tooltipster

These settings have effect only in tooltips.

hoverxref_tooltip_class

Description: CSS class to add to div created for the tooltip

Default: rst-content

Type: string

hoverxref_tooltip_lazy

Description: Whether to lazily generate tooltips (insert the HTML for the tooltip on hover, rather than on page load). This is known to be slower, but prevents the browser from stalling on load for very big doc pages. We recommend you keeping it as False unless you are experiencing page load issues.

Default False

Type: bool

Warning

The following settings are passed directly to Tooltipster. See its options for more information about their descriptions.

hoverxref_tooltip_theme

Default: ['tooltipster-shadow', 'tooltipster-shadow-custom']

Type: list of strings

hoverxref_tooltip_interactive

Default: True

Type: bool

hoverxref_tooltip_maxwith

Default: 450

Type: int

hoverxref_tooltip_side

Default: right

Type: string

hoverxref_tooltip_animation

Default: fade

Type: string

hoverxref_tooltip_animation_duration

Default: 0

Type: int

hoverxref_tooltip_content

Default: Loading...

Type: string

MicroModal.js

These settings have effect only in modal dialogues.

hoverxref_modal_hover_delay

Description: Delay time (in milliseconds) before showing the modal when hover over a ref

Default: 350

Type: int

hoverxref_modal_default_title

Description: Title shown when the content does not have one

Default: Note

Type: string

hoverxref_modal_prefix_title

Description: Prefix included in the title of the modal

Default: 📝 (ends with a trailing space)

Type: string

hoverxref_modal_class

Description:

Default: rst-content

Type: string

Warning

The following settings are passed directly to MicroModal.js. See https://micromodal.now.sh/#configuration for more information about their descriptions.

hoverxref_modal_onshow_function

Default: None

Type: string

hoverxref_modal_openclass

Default: is-open

Type: string

hoverxref_modal_disable_focus

Default: True

Type: bool

hoverxref_modal_disable_scroll

Default: False

Type: bool

hoverxref_modal_awaitopenanimation

Default: False

Type: bool

hoverxref_modal_awaitcloseanimation

Default: False

Type: bool

hoverxref_modal_debugmode

Default: False

Type: bool