Sphinx Tippy#

GitHub Repo stars

Get rich hover tips in your sphinx documentation.

Hover on me!

Installation#

Install with pip:

pip install sphinx-tippy

Usage#

Add the extension to your conf.py:

extensions = ["sphinx_tippy"]

Now your website will have tooltips on many of your links!

Important

Dependent on the theme you ar using with sphinx, you may need to add some CSS to your conf.py to make the tooltips show correctly.

For example, for the Pydata Sphinx Theme:

conf.py:

html_static_path = ['_static']
html_css_files = ["tippy.css"]

_static/tippy.css:

.tippy-box {
    background-color:var(--pst-color-surface);
    color:var(--pst-color-text-base);
    border: 1px solid var(--pst-color-border);
}

How does it work?#

The extension uses the tippy.js library to create tooltips.

Currently, all tips are created during the build process, so there is no need for a server and, once loaded, all tips are very responsive (although dynamic fetching could be implemented later).

The internal tips are created simply by “scraping” the built HTML, which bypasses having to deal with the sphinx internals, like domains etc.

Note, there is another sphinx extension for hover tips; sphinx-hoverxref, however, one of the annoyances with this is that documentation has to be hosted on Read the Docs for it to work, since that used the RTD embed API dynamically.

Configuration#

The extension has the following configuration options.

Display#

tippy_props#

Overrides for the tippy.js props to use, by default:

tippy_props = {"placement": "auto-start", "maxWidth": 500, "interactive": False, "arrow": True}

Note, only the placement, maxWidth, theme, and interactive props are allowed to be overridden currently.

tippy_add_class#

Add a class name to all elements with tips.

For example this can be used to change the style of the cursor when hovering over a tip (see html_css_files):

conf.py:

html_static_path = ['_static']
html_css_files = ["tippy.css"]
tippy_add_class = "has-tippy"

_static/tippy.css:

.has-tippy:hover {
    cursor: help;
}

Filters#

These configurations enable filtering of what tips are created, and shown.

tippy_skip_urls#

A list of URL regexes to skip, for example:

tippy_skip_urls = [
    "https://example.com/name_prefix.*",
]
tippy_tip_selector#

Define what elements tips are created for, by default:

tippy_tip_selector = "figure, table, img, p, aside, div.admonition, div.literal-block-wrapper"
tippy_skip_anchor_classes#

Skip showing tooltips for anchors with these classes, by default:

tippy_skip_anchor_classes = (
    "headerlink",
    "sd-stretched-link",
)
tippy_anchor_parent_selector#

Only show tool tips for anchors within this select, by default "", examples:

# For Furo theme:
tippy_anchor_parent_selector = "div.content"
# For pydata theme:
tippy_anchor_parent_selector = "article.bd-article"

External APIs#

These configurations enable fetching tips from external APIs.

tippy_rtd_urls#

A list of URL prefixes to use for ReadTheDocs tooltips (using the /api/v3/embed/ API), for example:

tippy_rtd_urls = [
    "https://www.sphinx-doc.org/en/master/",
]

This works for any ReadTheDocs hosted documentation. It works well with the intersphinx extension.

tippy_enable_wikitips#

Enable tooltips for wikipedia links, starting https://en.wikipedia.org/wiki/, by default True.

tippy_enable_doitips#

Enable tooltips for DOI links, starting https://doi.org/, by default True.

tippy_doi_api#

The API to use for DOI tooltips, by default https://api.crossref.org/works/ (another possibility is https://api.datacite.org/dois/)

tippy_doi_template#

The jinja template to use for formatting DOI data to tooltips, by default:

{% set attrs = data.message %}
<div>
    <h3>{{ attrs.title[0] }}</h3>
    {% if attrs.author is defined %}
    <p><b>Authors:</b> {{ attrs.author | map_join('given', 'family') | join(', ')  }}</p>
    {% endif %}
    <p><b>Publisher:</b> {{ attrs.publisher }}</p>
    <p><b>Published:</b> {{ attrs.created['date-parts'][0] | join('-') }}</p>
</div>

(See https://github.com/CrossRef/rest-api-doc/blob/master/api_format.md)

Miscellaneous#

tippy_custom_tips#

A dictionary, mapping URLs to HTML strings, which will be used to create custom tips.

For example, to add a tip for the URL https://example.com:

tippy_custom_tips = {
    "https://example.com": "<p>This is a custom tip!</p>"
}
tippy_enable_mathjax#

Whether to enable tooltips for math equations, by default False.

Note, this requires the sphinx.ext.mathjax extension to be enabled. At present it will cause mathjax to be loaded on every page, even if it is not used.

tippy_js#

The Javascript required to enable tooltips, by default:

tippy_js = ("https://unpkg.com/@popperjs/core@2", "https://unpkg.com/tippy.js@6")