Using sphinx autodoc for a fabfile

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

Its because you've applied decorator on your function setup_development

you need to update your task function with functools.wraps as below,

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

If you document decorated functions or methods, keep in mind that autodoc retrieves its docstrings by importing the module and inspecting the __doc__ attribute of the given function or method.

That means that if a decorator replaces the decorated function with another, it must copy the original __doc__ to the new function. From Python 2.5, functools.wraps() can be used to create well-behaved decorating functions.

References:

• Python Sphinx autodoc and decorated members

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