使用sphinx autodoc生成fabfile [英] Using sphinx autodoc for a fabfile

问题描述

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

Is it possible to use Sphinx autodoc to generate documentation for my fabfile, from the function docstrings?

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

E.g. for a fabfile containing a setup_development task i've tried:

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

但是什么也没生成。

fabfile片段：

fabfile snippet:

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

推荐答案

我能够生成带有保留函数签名的完整文档通过使用 decorator_apply 食谱在中找到 rel = nofollow> 装饰器 模块。

I was able to produce full documentation with preserved function signature by using the decorator_apply recipe found in the documentation for the decorator module.

""" 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来源：

This is the simple ReST source that I used:

.. automodule:: myfabfile
   :members:

一些评论：

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

The answer submitted by shahjapan explains how to preserve the docstring in the general case, but it does not address the fact that the @task decorator is defined in an external library.

无论如何，事实证明，使用 @task 装饰的函数会自动保留docstring。以下是 __ init __ 方法中的内容Fabric的 tasks.WrappedCallableTask 类：

Anyway, it turns out that the docstring is preserved automatically for functions decorated with @task. The following is in the __init__ method of Fabric's tasks.WrappedCallableTask class:

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

（需要显式的。autofunction :: 。）为确保也保留了函数签名，请使用 decorator mod ule可以如上所述使用。

So that already works as it is (an explicit .. autofunction:: is needed). To ensure that the function signature is preserved as well, the decorator module can be used as shown above.

更新

装饰器模块的使用破坏了Fabric的工作方式（请参见注释）。因此，这毕竟不可行。或者，我建议使用以下修改的reST标记：

The use of the decorator module breaks things in the workings of Fabric (see comment). So that may not be feasible after all. As an alternative I suggest the following modified reST markup:

.. automodule:: myfabfile2
   :members: 

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

也就是说，您必须包括完整的功能签名。这也是Sphinx文档中建议的内容（请参见从该方法被装饰器隐藏。）。

That is, you'll have to include the full function signature. This is also what is suggested in the Sphinx documentation (see "This is useful if the signature from the method is hidden by a decorator.").

这篇关于使用sphinx autodoc生成fabfile的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！