引用NumPy标量类型时Sphinx触发警告的解决方法咨询

问题背景 #

使用Sphinx的nitpicky模式处理含NumPy类型注解的代码时：

import numpy as np
import numpy.typing as npt

def func(x: npt.NDArray[np.double]) -> None:
    """My func docstring."""

会触发如下警告：

py:class reference target not found: numpy.float64

原因是：np.double是np.float64的别名，Sphinx解析类型注解时会解析到实际类型np.float64，但NumPy的objects.inv中numpy.float64被标记为py:attribute而非py:class，nitpicky模式下Sphinx按py:class查找时找不到对应条目。

解决方案 #

方案1：忽略特定警告 #

在Sphinx配置文件conf.py中添加nitpick_ignore列表，跳过对目标引用的检查：

nitpick_ignore = [
    ("py:class", "numpy.float64"),
    # 若有其他NumPy标量类型警告，可追加条目，例如：
    # ("py:class", "numpy.int64"),
    # ("py:class", "numpy.bool_"),
]

该方法简单直接，无需修改代码或复杂配置。

方案2：修正Intersphinx映射 #

先确保conf.py中已配置NumPy的intersphinx映射：

intersphinx_mapping = {
    'numpy': ('https://numpy.org/doc/stable/', None),
}

再添加以下代码修改inventory，将py:attribute类型的NumPy标量映射到py:class类别：

from sphinx.ext.intersphinx import fetch_inventory

def patch_numpy_inventory(app, config):
    # 从intersphinx配置中获取NumPy的文档地址
    numpy_url = config.intersphinx_mapping.get('numpy', (None, None))[0]
    if not numpy_url:
        return
    inv = fetch_inventory(app.env, app.config, numpy_url)
    if inv and "py:attribute" in inv:
        # 需修正的NumPy标量类型列表
        target_scalars = ["numpy.float64", "numpy.double", "numpy.int64", "numpy.bool_"]
        for scalar in target_scalars:
            if scalar in inv["py:attribute"]:
                inv["py:class"][scalar] = inv["py:attribute"][scalar]
    return inv

def setup(app):
    app.connect("config-inited", patch_numpy_inventory)

此方法从根源修正引用匹配逻辑，无需忽略警告，同时复用已有的intersphinx配置。

方案3：调整代码中的类型注解 #

直接将代码中的别名替换为实际类型，例如把np.double改为np.float64：

def func(x: npt.NDArray[np.float64]) -> None:
    """My func docstring."""

配合方案1或方案2使用，可彻底消除警告。

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