重要

根据你在 Sphinx 中使用的主题，你可能需要在 conf.py 中添加一些 CSS，以确保工具提示正确显示。

例如，对于 Pydata Sphinx 主题：

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);
}

如何工作？¶

该扩展使用 tippy.js 库来创建工具提示。

目前，所有提示都是在构建过程中创建的，因此不需要服务器，一旦加载，所有提示都非常响应迅速（尽管未来可以实现动态获取）。

内部提示是通过简单地“抓取”构建的 HTML 创建的，这绕过了处理 Sphinx 内部结构（如域等）的复杂性。

请注意，还有另一个用于悬停提示的 Sphinx 插件：sphinx-hoverxref，然而，它的令人烦恼的地方是文档必须托管在 Read the Docs 上才能正常工作，因为它动态使用了 RTD 嵌入 API。

配置¶

该插件具有以下配置选项。

展示¶

tippy_props¶

默认情况下，用于覆盖 tippy.js 属性的设置如下：

tippy_props = {"placement": "auto-start", "maxWidth": 500, "interactive": False, "theme": "material", "duration": [200, 100], "delay": [200, 500]}

注意，目前只允许覆盖以下属性：

tippy_add_class¶

Add a class name to all elements with tips.

例如，这可以用于更改悬停在提示上时的光标样式（参见 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;
}

过滤¶

这些配置可以筛选创建和显示的提示内容。

tippy_skip_urls¶

URL 正则表达式列表，用于跳过某些内容，例如：

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

tippy_tip_selector¶

默认情况下，定义哪些元素会生成提示：

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

tippy_skip_anchor_classes¶

默认情况下，跳过显示具有这些类的锚点的工具提示：

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

tippy_anchor_parent_selector¶

默认情况下，仅显示此选择范围内的锚点的工具提示，默认为 ""，例如：

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

外部 APIs¶

这些配置支持从外部 API 获取提示信息。

tippy_rtd_urls¶

URL 前缀列表，用于 ReadTheDocs 工具提示（使用 /api/v3/embed/ API），例如：

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

这适用于任何托管在 ReadTheDocs 上的文档。它与 intersphinx 扩展配合良好。

tippy_enable_wikitips¶: 默认情况下，启用维基百科链接的工具提示，链接以 https://en.wikipedia.org/wiki/ 开头，默认为 True。

tippy_enable_doitips¶: 默认情况下，启用 DOI 链接的工具提示，链接以 https://doi.org/ 开头，默认为 True。

tippy_doi_api¶: 用于 DOI 工具提示的 API，默认为 https://api.crossref.org/works/ （另一种可能是 https://api.datacite.org/dois/）。

tippy_doi_template¶

用于将 DOI 数据格式化为工具提示的 jinja 模板，默认为：

{% 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)

其他配置¶

tippy_custom_tips¶

字典，将 URL 映射到 HTML 字符串，用于创建自定义提示。

例如，为 URL https://example.com 添加提示：

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

tippy_enable_mathjax¶

是否启用数学方程的工具提示，默认为 False。

请注意，这需要启用 sphinx.ext.mathjax 扩展。目前，它会导致 mathjax 在每个页面上加载，即使未使用数学公式。

tippy_js¶

启用工具提示所需的 Javascript，默认为：

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