使用元类RequestMeta的类调用Sphinx autoclass无法生成成员文档怎么办

根因分析 #

你的自定义元类RequestMeta在创建类时，会遍历类的所有属性，将所有可调用对象通过decimal_to_string转换后再赋值给新类。如果decimal_to_string没有保留原函数的元数据（包括文档字符串、函数名、所属类信息等），Sphinx的autodoc模块就无法识别转换后的对象是类的有效成员，也读取不到对应的注释内容，因此无法生成成员文档。

修复方案 #

方案1：保留被装饰函数的元数据（推荐） #

给decimal_to_string装饰器添加functools.wraps逻辑，保留原函数的所有元信息，不需要修改其他业务逻辑：

from functools import wraps

def decimal_to_string(func):
    @wraps(func) # 新增该行，自动复制原函数的元数据
    def inner(*args, **kwargs):
        # 原有decimal_to_string的业务逻辑
        ...
    return inner

方案2：调整元类的属性过滤规则 #

如果不需要对类的方法做decimal_to_string转换，可以修改元类逻辑，跳过对类方法的处理：

class RequestMeta(type):
    def __new__(mcs, what, bases, attrs):
        _attrs = {}
        for name, attr in attrs.items():
            # 跳过魔术方法、普通类方法的转换，按需调整过滤规则
            if callable(attr) or name.startswith('__'):
                _attrs[name] = attr
            else:
                _attrs[name] = decimal_to_string(attr)
        return super().__new__(mcs, what, bases, _attrs)

方案3：修改Sphinx配置强制导出成员 #

如果不想修改业务代码，可以直接在rst文件中明确指定要导出的成员，绕过autodoc的自动扫描逻辑：

.. autoclass:: my_prog.a.Class_name
   :members: test

也可以在Sphinx项目的conf.py中添加全局配置，放宽autodoc的成员识别规则：

# conf.py 新增以下配置
autodoc_default_options = {
    "members": True,
    "undoc-members": True,
}

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