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

Question

我有一个项目，其中一些功能以 napoleon numpy 风格记录。本着 numpyness 的精神，我有一堆 class 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

这工作得很好，类型包含在没有 link 的输出中：

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

/.../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 文档中的任何地方找到有意义的参考“预处理”。

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

Answer 1

通过 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，但在我的设置过程中的某个地方，它被取消设置。格外安全永远不会有坏处。

到link到array_like term on the numpy site, the intersphinx extension must be enabled, and intersphinx_mapping在conf.py必须link到numpy:

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

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

Using array-like as a type in napoleon without warning

python

python-sphinx

numpydoc

sphinx-napoleon