python - 将 sphinx autodoc 用于 fabfile

Question

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

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

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

但是没有生成任何东西。

fab文件片段:

@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 and decorated members

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