20

我有一些在 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 就可以正常工作。

4

1 回答 1

24

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

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

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

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

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/conf.py#L195

对于异常文件本身:

https://github.com/astropy/astropy/blob/35501fcba6811705fcd53669742db8346727672d/docs/nitpick-exceptions

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

于 2015-06-03T15:10:12.740 回答