Napoleon NumPy风格文档使用array-like类型时如何消除Sphinx引用告警

告警根因 #

Sphinx的Python域在解析Napoleon提取的参数类型时，会默认将每个类型名识别为需要全局查找的Python类/对象，自动尝试生成跳转超链接。当类型是NumPy生态通用的array-like这类并非真实Python对象的惯例标注时，就会因为找不到对应的可解析目标触发告警。
你提到的Sphinx PR #7690，正是为了解决这类惯例类型的解析问题，在Sphinx 4.0版本中落地了类型别名的原生支持能力。

适配高版本Sphinx（≥4.0）的最优方案 #

直接利用PR #7690引入的内置配置，在项目文档的conf.py文件中注册自定义类型别名，从根源阻止Sphinx对这类类型的引用查找：

python_type_aliases = {
    # 把项目中用到的惯例类型全部映射为纯文本渲染的别名
    "array-like": "array-like",
    "array_like": "array_like",
}

• 该配置的作用是：Sphinx遇到匹配的类型名时，直接按纯文本渲染，不再触发类引用查找逻辑，自然不会产生告警。
• 全程不需要修改任何业务代码中的文档字符串，完全兼容现有NumPy风格的编写惯例。

低版本Sphinx（<4.0）兼容方案 #

如果使用的Sphinx版本低于4.0，没有内置的python_type_aliases配置，可通过以下两种方式实现同等效果，消除告警：

• 配置引用忽略规则：在conf.py中添加告警过滤规则，直接跳过对已知惯例类型的引用检查：

  nitpick_ignore = [
      ("py:class", "array-like"),
      ("py:class", "array_like"),
  ]
  

  该配置不会影响类型文本的正常渲染，仅跳过无意义的引用查找告警。
• 添加文档字符串预处理钩子：在conf.py中注册autodoc处理钩子，批量替换文档中的特殊类型标注，阻止RST解析器将其识别为引用目标：

  def autodoc_process_docstring(app, what, name, obj, options, lines):
      # 遍历所有文档行，替换需要纯文本渲染的类型名
      for idx, line in enumerate(lines):
          lines[idx] = line.replace("array-like", r"\array-like")
  
  def setup(app):
      app.connect("autodoc-process-docstring", autodoc_process_docstring)
  

文档字符串层面的临时规避方式 #

如果不想修改全局配置，也可以在编写NumPy风格文档时，将非实体的类型名用单引号包裹，标记为纯文本内容：

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

单引号包裹的类型名会被Sphinx识别为纯文本，不会触发引用查找逻辑。

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