Sphinx：从 C 中实现的基类继承的类的 Autodocs

Question

从collections.deque继承时，我遇到了错误/警告。 狮身人面像抱怨：

utils.py:docstring of utils.Test.count:1: WARNING: py:class reference target not found: integer -- return number of occurrences of value

对于这个例子， utils.py只包含

from collections import deque

class Test(deque):
    pass

我最好的猜测是，这可能是由在 C 中实现的deque引起的，因为integer不是有效的 Python 类型。 环顾四周，我在collections的 CPython 源代码中发现了这一行，如果我的假设是正确的话，它可能正是那部分。 但我对 CPython、Sphinx autodoc 的内部工作原理以及这些世界之间的边界一无所知。

是否有一个好的解决方案来纠正这个问题，无论是在 CPython 的注释中还是在 autodoc 插件中？

Answer 1

看来我或多或少是在赚钱。 integer在其他地方使用并且似乎有效，但更重要的是，Sphinx 期望文档字符串遵循PEP 7中概述的示例，该示例建议将签名放在第一行（在任何其他文档之前跟一个换行符）。 因此，它会查找由->和\n之间的整个字符串命名的 class，在我的例子中是integer -- return number of occurrences of value 。

解决方法是将所有这些字符串放入nitpick_ignore ：

    # Wrong docstrings in the CPython source of collections.queue
    ("py:class", "-- reverse *IN PLACE*"),
    ("py:class", "integer -- return first index of value."),
    ("py:class", "integer -- return number of occurrences of value"),
    ("py:class", "-- insert object before index"),
    ("py:class", "-- remove first occurrence of value."),
    ("py:class", "-- size of D in memory, in bytes"),
    ("py:class", "-- return a reverse iterator over the deque"),

正确的解决方法是相应地更改 CPython 代码中的文档。

我正要这样做，当我发现我的同事比我早了 2 周。 但在他打开的问题上，一位核心开发人员争辩说，这个方案只不过是一个例子，文档只需要是人类可读的，而不是指定确切的类型。 所以看起来不会很快有修复。