跨包继承Sphinx父类：如何禁用反引号引用警告

1. 为什么NetworkX自己构建文档不报错，而我的项目会？ #

NetworkX的Sphinx构建配置里已经做了针对性处理，规避了这类警告：

• 他们大概率在conf.py中配置了nitpick_ignore或nitpick_ignore_regex，直接忽略了这些无法解析的引用警告；
• 或者通过numpydoc_xref_ignore配置，告诉numpydoc不要尝试解析文档字符串中代码示例里的反引号内容为跨引用；
• 另外，NetworkX可能通过自定义扩展，让代码块中的反引号仅作为代码高亮标记，不触发跨引用解析。

而你的项目默认没有这些配置，当autodoc继承NetworkX父类的文档字符串时，numpydoc会把所有反引号包裹的内容都当作Python对象引用去查找。像G = nx.DiGraph(D)这种代码语句、edges is None这种表达式显然不是合法的可引用对象，所以Sphinx抛出"reference target not found"警告。

2. 如何禁用或规避这些警告？ #

以下是几种可行方案，按推荐度排序：

方案1：通过numpydoc配置忽略无效引用 #

在Sphinx的conf.py中添加numpydoc的忽略规则，直接跳过对这些无效内容的跨引用解析：

numpydoc_xref_ignore = {
    "G = nx.DiGraph(D)",
    "edges is None",
    "nodes is None",
    # 可继续添加其他出现警告的内容
}

如果警告条目太多，也可以用numpydoc_xref_param_type = False关闭对参数类型的自动引用解析（注：这会影响所有参数类型的链接，按需使用）。

方案2：用Sphinx的nitpick忽略警告 #

在conf.py中配置nitpick_ignore，忽略特定类型的无效引用：

nitpick_ignore = [
    ("py:obj", "G = nx.DiGraph(D)"),
    ("py:obj", "edges is None"),
    ("py:obj", "nodes is None"),
]

如果想批量忽略所有类似的代码语句引用，可以用nitpick_ignore_regex（需要Sphinx 3.0+）：

nitpick_ignore_regex = [
    ("py:obj", r".*=.*"),  # 忽略包含等号的引用
    ("py:obj", r".* is None"),  # 忽略"xxx is None"格式的引用
]

方案3：禁止继承父类文档字符串（不推荐） #

在conf.py中设置：

autodoc_inherit_docstrings = False

但这样你的子类文档会丢失NetworkX父类的文档内容，除非手动重写所有方法的文档字符串，一般不建议使用。

方案4：自定义扩展处理文档字符串 #

编写简单的Sphinx扩展，在解析文档字符串前，把代码块中的反引号替换成双反引号（Sphinx中双反引号仅表示代码高亮，不触发跨引用），或者直接移除这些反引号的解析逻辑。该方案需要一定的Sphinx扩展开发知识，适合复杂场景。

3. 问题原理深度解析 #

核心逻辑：Numpydoc的反引号解析规则 #

Numpydoc作为Sphinx的扩展，对文档字符串的解析遵循规则：文档字符串中的单个反引号内容会被解析为Python对象的跨引用（xref），Sphinx会尝试在项目文档或已安装模块中找到对应对象，找不到就会抛出警告。

NetworkX的文档字符串中，很多反引号用于代码示例（比如G = nx.DiGraph(D)），这些内容并不是真正的可引用对象（如类、函数、变量），而是完整的代码语句或表达式。当你的项目继承这些文档字符串后，numpydoc依然会尝试解析它们为跨引用，自然找不到目标，触发警告。

NetworkX的规避逻辑 #

NetworkX维护者提前处理了这个问题：要么通过numpydoc_xref_ignore告诉numpydoc不要解析这类内容，要么通过nitpick_ignore让Sphinx直接忽略这类警告，从而保证自身文档构建过程无报错。

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