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.

Warning

Only Python Domain (py) is currently supported.

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. This is a current limitation that we hope to remove in the future.

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

Warning

You shouldn’t modify the following three settings (api_host, project, version) unless you know what you are doing. Their defaults should be fine to build the documentation and make it work in Read the Docs.

hoverxref_api_host

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

Default: https://readthedocs.org

Type: string

hoverxref_project

Description: Read the Docs project slug

Default: It defaults to READTHEDOCS_PROJECT environment variable

Type: string

hoverxref_version

Description: Read the Docs version slug

Default: It defaults to READTHEDOCS_VERSION environment variable

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

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