如何让Sphinx优雅忽略intersphinx映射中的第三方引用目标

方案一：直接跳过所有外部模块的引用有效性检查 #

如果希望Sphinx不对包外的任何模块引用做有效性验证，可以在conf.py中配置nitpick_ignore_regex，用正则匹配所有外部引用：

# conf.py
nitpick_ignore_regex = [
    (r'py:.*', r'.*'),  # 忽略所有Python类型/对象的引用检查
]

这样配置后，Sphinx会直接认定所有外部引用有效，不再抛出相关警告。但要注意，这会同时忽略你自己包内可能存在的无效引用，建议仅在确认内部引用无误时使用。

方案二：手动指定需忽略的特定引用目标 #

如果想保留警告提示，仅忽略确认过的外部引用，可以在conf.py中使用nitpick_ignore列表，逐个添加需要忽略的引用项。

针对你遇到的ndarray.reshape引用警告，添加如下配置：

# conf.py
nitpick_ignore = [
    ('py:obj', 'ndarray.reshape'),
    # 后续遇到其他需要忽略的引用，按同样格式添加即可
]

每次构建文档时，Sphinx仍会输出未被忽略的引用警告，你可以根据警告内容判断是否需要添加到nitpick_ignore中。

针对你的代码示例补充说明 #

你的MyArrayClass.shape属性的文档字符串中，可能隐含了对ndarray.reshape的引用（比如通过:ref:或自动解析的交叉引用）。添加上述配置后，对应的警告docstring of mypackage.MyArrayClass.shape:12: WARNING: 'any' reference target not found: ndarray.reshape就会被屏蔽。

内容的提问来源于stack exchange，提问作者Jake Stevens-Haas