Python Sphinx autodoc 和装饰成员

Question

我正在尝试使用 Sphinx 来记录我的 Python 类。我使用自动文档这样做:

.. 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

有一个不正确的原型(prototype)，例如 open(*args, **kwargs)。

我该如何解决这个问题？我的印象是使用 @wraps 可以解决这种问题。

Answer 1

我在使用 celery @task 装饰器时遇到了同样的问题。

您也可以通过将正确的函数签名添加到您的 rst 文件来解决此问题，如下所示:

.. 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 应用的 tasks.py 模块中指定我的 celery 任务的签名:

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

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