让Sphinx显示被装饰器包装的函数参数

Question

我正在使用sphinx来给一个项目写文档，但在处理被装饰器包裹的函数时遇到了问题。我看到过类似的问题，但没有一个解决方案适合我的情况。

我有成百上千个函数，这些函数都被一个自定义的装饰器包裹，而这个装饰器本身还可以接受参数。

from functools import wraps

def CustomFunctionDecorator(id, name):
    """Custom decorator"""
    def outer(f):

        @wraps(f)
        def inner(*args, **kwargs):
            ...do stuff....
            f(*args, **kwargs)

        return inner

    return outer

我的函数看起来是这样的：

@CustomFunctionDecorator(123, 'Test')
def TestFunction(a, b, c=None):
    """Test Documentation"""
    ..do something....

现在，当我使用sphinx和autodoc来生成文档时，所有被CustomFunctionDecorator包裹的函数在sphinx文档中隐藏了函数的实际参数，显示成这样：

TestFunction(*args, **kwargs)

测试文档

文档是可以工作的，但函数的参数却不行……

有什么想法吗？希望我说得够清楚。

Answer 1

根据这个回答：

functools.wraps 只保留了 __name__、__doc__ 和 __module__ 这几个属性。如果你想同时保留函数的签名，可以看看 Michele Simionato 的Decorator模块。

这算是一种变通方法，而不是解决方案，不过根据文档（我强调一下）：

你可以用常规语法来覆盖那些明确记录的可调用对象（函数、方法、类）的签名，这样就能覆盖通过反射得到的签名：

.. autoclass:: Noodle(type)

   .. automethod:: eat(persona)  

如果方法的签名被装饰器隐藏了，这就很有用。

在0.4版本中新增。

显然，这对“成百上千个函数”来说可不是什么好事……