Question

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

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

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

But nothing is generated.

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>

Answer 1

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

This is the simple ReST source that I used:

.. automodule:: myfabfile
   :members:

Some comments:

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.

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__

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.

---

Update

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')

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