在没有警告的情况下在拿破仑中使用类似数组的类型

如何解决在没有警告的情况下在拿破仑中使用类似数组的类型

我有一个项目，其中一些功能以拿破仑 numpy 风格记录。本着 numpyness 的精神，我有一堆 array-like 类的函数参数。下面是一个例子：

def foo(x,y):
    """
    Foo the arguments together to make a bar.

    Parameters
    ----------
    x : array-like
        This is an argument.
    y : array-like
        I like it,give me another!

    Returns
    -------
    bar : numpy.ndarray
        Works every time
    """
    pass

这很好用，并且类型包含在没有链接的输出中：

问题是我在每个函数的每一行都收到警告：

/.../my_project/my_module.py:docstring of my_project.my_module.foo:: WARNING: py:class reference target not found: array-like
/.../my_project/my_module.py:docstring of my_project.my_module.foo:: WARNING: py:class reference target not found: array-like

我相当相信有一些解决方案。 PR #7690 似乎以某种方式解决了这个问题，但我在拿破仑或更广泛的 sphinx 文档中找不到任何有意义的“预处理”参考。

那么我该如何摆脱警告？

解决方法

深入研究 PR，我找到了可以查看的位置：napoleon_type_aliases 配置项允许您为 array-like、dict-like 等设置映射。在这种特殊情况下，将以下内容添加到 conf.py 就可以了：

napoleon_use_param = True
napoleon_type_aliases = {
    'array-like': ':term:`array-like <array_like>`','array_like': ':term:`array_like`',}

napoleon_use_param 必须是 True 才能工作。它被记录为默认为 True，但在我的设置过程中，它未设置。额外安全从来没有坏处。

要链接到 numpy 站点上的 array_like 术语，必须启用 intersphinx 扩展名，并且 conf.py 中的 intersphinx_mapping 必须链接到 numpy：

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