Sphinx Autodoc继承C实现基类（如deque）的警告问题

问题原因 #

你的猜测完全正确：deque的count方法由C实现，它的文档字符串里使用了非标准的类型标注integer——Python官方并没有这个类型名称，标准写法应为int。Sphinx Autodoc在解析子类继承来的文档字符串时，会将integer视为类型引用去查找对应的py:class节点，找不到就会抛出警告。

修正方案 #

方案一：重写count方法并修正文档字符串 #

直接在子类中重写count方法，替换掉有问题的类型标注，同时调用父类实现保证功能不变：

from collections import deque

class Test(deque):
    def count(self, value):
        """Return number of occurrences of value.
        
        :param value: The value to count
        :type value: int
        :return: Number of occurrences
        :rtype: int
        """
        return super().count(value)

这种方式简单直接，无需修改Sphinx配置或编写插件。

方案二：用Sphinx钩子批量修正文档字符串 #

如果不想逐个重写方法，可以通过Sphinx的autodoc-process-docstring钩子，在解析文档字符串时自动替换integer为int。在Sphinx配置文件（通常是conf.py）中添加以下代码：

def fix_deque_docstring(app, what, name, obj, options, lines):
    # 仅处理目标子类的方法文档
    if hasattr(obj, '__qualname__') and 'Test.' in obj.__qualname__:
        for i, line in enumerate(lines):
            lines[i] = line.replace('integer', 'int')

def setup(app):
    app.connect('autodoc-process-docstring', fix_deque_docstring)

该钩子会在Autodoc处理文档字符串时触发，自动完成类型标注的替换，解决引用找不到的问题。

方案三：自定义Autodoc扩展（进阶） #

如果需要处理更多C实现类的类似文档问题，可以编写通用Autodoc扩展，批量修正非标准类型标注：

from sphinx.ext.autodoc import MethodDocumenter

class FixedMethodDocumenter(MethodDocumenter):
    def add_content(self, more_content, no_docstring=False):
        super().add_content(more_content, no_docstring)
        # 定义非标准类型到标准类型的映射
        type_map = {'integer': 'int', 'string': 'str', 'long': 'int'}
        if self.docstring:
            for old_type, new_type in type_map.items():
                self.docstring = self.docstring.replace(old_type, new_type)

def setup(app):
    app.add_autodocumenter(FixedMethodDocumenter, override=True)

将这段代码放到conf.py中，或做成独立扩展模块引入，就能自动修正所有继承自C实现类的方法文档中的类型标注问题。

总结 #

• 简单场景优先选方案一，代码直观易维护；
• 多子类/多方法场景用方案二，批量修正更高效；
• 需处理大量C扩展类的场景用方案三，扩展性更强。

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