Python Sphinx autodoc和装饰成员

Question

我试图使用Sphinx来记录我的Python类.我这样做是使用autodoc:

.. autoclass:: Bus
   :members:

虽然它正确地获取我的方法的文档字符串,那些装饰:

    @checkStale
    def open(self):
        """
        Some docs.
        """
        # Code

与@checkStale存在

def checkStale(f):
    @wraps(f)
    def newf(self, *args, **kwargs):
        if self._stale:
            raise Exception
        return f(self, *args, **kwargs)
    return newf

有一个不正确的原型,如open(*args, **kwargs).

我怎样才能解决这个问题？我的印象是使用@wraps会修复这种事情.

Answer 1

扩展我的评论:

您是否尝试过使用装饰器包并将@decorator放在checkStale上？我使用epydoc和装饰函数有类似的问题.

正如您在评论中提到的那样,装饰器包不是标准库的一部分.

您可以使用以下代码(未经测试)回退:

try:
    from decorator import decorator
except ImportError:
    # No decorator package available. Create a no-op "decorator".
    def decorator(f):
        return f

Answer 2

我和芹菜@task装饰器有同样的问题.

您也可以通过向第一个文件添加正确的函数签名来解决此问题,如下所示:

.. autoclass:: Bus
    :members:

    .. automethod:: open(self)
    .. automethod:: some_other_method(self, param1, param2)

它仍然会自动记录非装饰成员.

这可以在http://www.sphinx-doc.org/en/master/ext/autodoc.html#directive-automodule的sphinx文档中提到- 搜索"如果方法中的签名被隐藏,则此选项很有用装饰师."

在我的例子中,我必须使用autofunction在django app的tasks.py模块中指定我的celery任务的签名:

.. automodule:: django_app.tasks
    :members:
    :undoc-members:
    :show-inheritance:

    .. autofunction:: funct1(user_id)
    .. autofunction:: func2(iterations)

Answer 3

我刚刚找到了一个适合我的简单解决方案，但不要问我为什么。如果你知道为什么在评论中添加它。

from functools import wraps 

def a_decorator(f):
    """A decorator 

    Args:
        f (function): the function to wrap
    """
    @wraps(f) # use this annotation on the wrapper works like a charm
    def wrapper(*args, **kwargs):
        some code
        return ret

return wrapper

装饰函数和装饰器的文档都被保留