文档助手

fabric.docs.unwrap_tasks(module, hide_nontasks=False)

module 中的任务对象替换为自己封装的函数。

具体来说,你可以将 WrappedCallableTask 的实例替换为其 .wrapped 属性(原先被封装的函数)。

它应该和 Sphinx 文档工具一起使用,使用在项目 conf.py 文件的底部,用于保证文档工具只会接触到“真正”的函数,不包括函数签名之类。通过使用 unwrap_tasks ,自动生成文档工具将不会发现文档签名(尽管任然能发现 __doc__ 等)。

例如,你可以在 conf.py 的底部写上:

from fabric.docs import unwrap_tasks
import my_package.my_fabfile
unwrap_tasks(my_package.my_fabfile)

只需要设置 hide_nontasks=True 就可以 隐藏 所有非任务函数,它保证所有这些对象不会被识别为任务,因此会被当作是私有的,Sphinx 自动生成文档时也会将其略过。

如果你的 fabfile 中混有子程序(subroutine)和任务,而你 希望将任务文档化, hide_nontasks 对你会非常有用。

如果你在 Fabric 代码实际运行环境中使用它(而非 Sphinx conf.py 中),请立即就医。(原文就是“please seek immediate medical attention”——译者注)