python - Sphinx autodoc 给出警告：py:class reference target not found: type warning

Question

我有一些在 python 中使用元类的代码。但是当 sphinx autodoc 运行时，它会给出错误：

WARNING: py:class reference target not found: type

错误发生在自动生成的 .rst 文件的一行中：

.. automodule:: API.list.blockList
    :members: # this is the line in error
    :show-inheritance:

并且 blockList 扩展了已\__metaclass__设置为我的元类的 API.list.list。

据我所知，sphinx 认为内置类型类不存在。我尝试导入内置类型以使 sphinx 意识到它的存在，但没有奏效。

如果我从 API.list.list 中删除元类分配，并从代码中删除元类，那么 sphinx 就可以正常工作。

score 24 · Accepted Answer

这只是 Python 文档本身中的一个错误——对某些 Python 内置函数（包括type）的引用无法正确解析（例如，参见https://bugs.python.org/issue11975）。

要使警告消失，您可以将该nitpick_ignore选项添加到您的 Sphinx 配置中。例如在 Astropy 项目中，我们有：

nitpick_ignore = [('py:class', 'type')]

事实上，有足够多的例外，我们只是将它们全部放在一个单独的文件中，然后再从中读出。看：

对于异常文件本身：

上述文件中的许多异常是特定于 Astropy 的，但其他一些异常解决了 Python 和 Numpy 中的一些损坏的引用，并且可能通常很有用。

1 回答 1