对 fabfile 使用 sphinx autodoc

Question

是否可以使用 Sphinx autodoc 从函数 docstrings 为我的 fabfile 生成文档？

例如，对于包含我尝试过的 setup_development 任务的 fabfile：

.. automodule::fabfile
   :members:
   .. autofunction:: setup_development

但没有生成任何内容。

fabfile 片段：

@task
def setup_development(remote='origin', branch='development'):
    """Setup your development environment.

    * Checkout development branch & pull updates from remote
    * Install required python packages
    * Symlink development settings
    * Sync and migrate database
    * Build HTML Documentation and open in web browser

    Args:
        remote: Name of remote git repository. Default: 'origin'.
        branch: Name of your development branch. Default: 'development'.
    """
    <code>

Answer 1

这是因为您在函数 setup_development 上应用了装饰器，

您需要使用 functools.wraps 更新您的 task 函数，如下所示，

from functools import wraps

def task(calling_func):
    @wraps(calling_func)
    def wrapper_func(self, *args, **kw):
        return calling_func(*args, **kw)
    return wrapper_func

如果您记录了装饰器函数或方法，请记住，autodoc 通过导入模块并检查给定函数或方法的 __doc__ 属性来检索其文档字符串。

这意味着如果装饰器用另一个装饰器替换被装饰的函数，它必须将原始的 __doc__ 复制到新函数。
从 Python 2.5 开始，functools.wraps() 可用于创建行为良好的装饰函数。

参考文献：

• Python Sphinx autodoc 和装饰成员

• https://www.sphinx -doc.org/en/master/usage/extensions/autodoc.html#directive-autoexception

Answer 2

通过使用decorator_apply配方可在 中找到rel="nofollow">装饰器模块。

""" myfabfile.py """

from fabric.api import task as origtask
from decorator import FunctionMaker

def decorator_apply(dec, func):
    return FunctionMaker.create(
        func, 'return decorated(%(signature)s)',
        dict(decorated=dec(func)), __wrapped__=func)

def task(func):
    return decorator_apply(origtask, func)

@task
def setup_development(remote='origin', branch='development'):
    """Setup your development environment.

    * Checkout development branch & pull updates from remote
    * Install required python packages
    * Symlink development settings
    * Sync and migrate database
    * Build HTML Documentation and open in web browser

    :param remote: Name of remote git repository.
    :param branch: Name of your development branch.
    """
    pass

这是我使用的简单 ReST 源：

.. automodule:: myfabfile
   :members:

一些评论：

shahjapan 提交的答案解释了如何在一般情况下保留文档字符串，但它没有解决定义 @task 装饰器的事实在外部库中。

不管怎样，事实证明，用 @task 修饰的函数会自动保留文档字符串。以下内容位于 Fabric 的 tasks.WrappedCallableTask 类的 __init__ 方法中：

if hasattr(callable, '__doc__'):
    self.__doc__ = callable.__doc__

因此，它已经按原样工作（显式的 .. autofunction::是需要的）。为了确保保留函数签名，可以使用如上所示的decorator模块。

---

更新

decorator 模块的使用破坏了 Fabric 的工作方式（参见评论）。所以这可能终究是不可行的。作为替代方案，我建议使用以下修改后的 reST 标记：

.. automodule:: myfabfile2
   :members: 

   .. autofunction:: setup_development(remote='origin', branch='development')

也就是说，您必须包含完整的函数签名。这也是 Sphinx 文档中建议的内容（请参阅 “如果签名该方法被装饰器隐藏。")。