如何让Sphinx Intersphinx生成plotly.graph_objects.Figure可点击链接？

已在conf.py中配置Plotly的Intersphinx映射：

intersphinx_mapping = {
    ...
    'plotly': ('https://plotly.com/python-api-reference/', None),
}

通过命令python -m sphinx.ext.intersphinx https://plotly.com/python-api-reference/objects.inv验证，Intersphinx清单包含目标条目：

plotly.graph_objects.Figure              generated/plotly.graph_objects.html#plotly.graph_objects.Figure

但使用Sphinx autodoc解析类型提示生成文档时，仅显示文本“Figure”，未生成指向Plotly官方文档的可点击链接。此前Python标准库、numpy、matplotlib的Intersphinx链接均正常工作，无警告。

补充细节 #

• 使用autoclass指令生成文档，文档字符串为Google Doc风格，通过Napoleon扩展转换，其他类/方法的文档生成均正常。
• 代码示例：

import plotly.graph_objects

class A:
    def b(self) -> plotly.graph_objects.Figure:
        """
        Returns:
            The plotly figure.
        """
        ...
        fig = plotly.graph_objects.Figure(
            data=[
                plotly.graph_objects.Sankey(
                    arrangement='perpendicular',
                    node=dict(
                        ...
                    ),
                    link=dict(
                        ...
                    )
                )
            ]
        )

        return fig

• 尝试过plotly.graph_objects.Figure和plotly.graph_objs.Figure两种写法；发现Plotly内部通过带下划线前缀子包的相对导入实现类型定义，导致PyCharm有提示，但代码中已使用完整限定名。
• 曾遇到numpy.typing类似问题，显式导入子包后解决，但本次已直接用Figure类创建实例，排除导入错误。
• 返回类型显示正确但无法点击，未收到Intersphinx相关警告。

1. 升级相关依赖 #

部分旧版Sphinx对复杂包结构的类型链接支持不足，先升级到最新稳定版：

pip install --upgrade sphinx sphinx.ext.intersphinx sphinxcontrib-napoleon

2. 清理缓存并启用调试日志 #

• 删除Sphinx构建目录（默认_build）和Intersphinx缓存目录（通常在_build/html/_static/intersphinx），重新构建文档，避免旧缓存干扰。
• 在conf.py中添加日志配置，查看Intersphinx的匹配过程：

import logging
logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger('sphinx.ext.intersphinx')
logger.setLevel(logging.DEBUG)

重新构建时检查日志，确认plotly.graph_objects.Figure是否被正确识别和匹配。

3. 显式导入并使用别名 #

由于Plotly内部的相对导入可能导致Sphinx无法解析完整路径，尝试显式导入并使用别名：

from plotly.graph_objects import Figure as PlotlyFigure

class A:
    def b(self) -> PlotlyFigure:
        """
        Returns:
            The plotly figure.
        """
        ...
        fig = PlotlyFigure(
            data=[
                plotly.graph_objects.Sankey(
                    arrangement='perpendicular',
                    node=dict(
                        ...
                    ),
                    link=dict(
                        ...
                    )
                )
            ]
        )

        return fig

别名方式可帮助Sphinx更准确匹配Intersphinx条目。

4. 检查Napoleon扩展配置 #

确保Napoleon正确传递类型提示给Intersphinx，在conf.py中确认：

extensions = [
    ...
    'sphinx.ext.autodoc',
    'sphinx.ext.intersphinx',
    'sphinxcontrib.napoleon',
]
napoleon_google_docstring = True
napoleon_use_param = True
napoleon_use_rtype = True

开启napoleon_use_rtype可确保返回类型被正确解析并传递给Intersphinx处理。

5. 手动指定类型链接 #

若自动解析仍失败，可在文档字符串中手动使用:class:指令强制生成链接：

class A:
    def b(self) -> plotly.graph_objects.Figure:
        """
        Returns:
            :class:`plotly.graph_objects.Figure`: The plotly figure.
        """
        ...

内容的提问来源于stack exchange，提问作者mkastner