在没有警告的情况下在拿破仑中使用类数组作为类型答案

【问题标题】：Using array-like as a type in napoleon without warning在没有警告的情况下在拿破仑中使用类数组作为类型
【发布时间】：2021-02-13 06:56:05
【问题描述】：

我有一个项目，其中包含一些以拿破仑 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 似乎以某种方式解决了这个问题，但我在拿破仑或更广泛的狮身人面像文档中的任何地方都找不到有意义的参考“预处理”。

那么我该如何摆脱警告呢？

【问题讨论】：

标签： python python-sphinx numpydoc sphinx-napoleon

【解决方案1】：

通过 PR 挖掘，我找到了查看位置：napoleon_type_aliases 配置项允许您为 array-like、dict-like 等设置映射。在这种特殊情况下，将以下内容添加到 @ 987654329@ 成功了：

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),
    ...
}

【讨论】：