Usando sphinx autodoc para un fabfile

Question

¿Es posible usar Sphinx autodoc para generar documentación para mi fabfile, desde la función docstrings?

E.g. para un fabfile que contiene una tarea setup_development he intentado:

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

sino que se genera nada.

fabfile fragmento:

@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

que era capaz de producir una documentación completa con la firma de función conservada mediante el uso de la receta decorator_applyfound in the documentation para el módulo decorator.

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

Ésta es la fuente simple descanso que he utilizado:

.. automodule:: myfabfile 
    :members: 

Algunos comentarios:

La respuesta presentada por shahjapan explica cómo preservar la cadena de documentación en el caso general, pero lo hace no aborda el hecho de que el decorador @task se define en una biblioteca externa.

De todos modos, resulta que el docstring se conserva automáticamente para las funciones decoradas con @task. El siguiente es en el método de la clase de tela tasks.WrappedCallableTask__init__:

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

Así que ya funciona como es (una explícita .. autofunction:: se necesita). Para garantizar que la firma de la función también se conserve, el módulo decorator se puede usar como se muestra arriba.

---

actualización

El uso del módulo decorator rompe cosas en el funcionamiento de Tela (ver comentario). Entonces eso puede no ser factible después de todo. Como alternativa, sugiero la siguiente marcación reST modificada:

.. automodule:: myfabfile2 
    :members: 

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

Es decir, deberá incluir la firma de la función completa. Esto también es lo que se sugiere en la documentación de Sphinx (vea "This is useful if the signature from the method is hidden by a decorator.").

Answer 2

Es porque usted ha solicitado decorador en su función de setup_development

que necesita para actualizar su función task con functools.wraps como abajo,

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 

Si documentar funciones o métodos, tenga en cuenta que autodoc recupera sus documentos importando el módulo e inspeccionando el atributo __doc__ de la función o método dados.

Eso significa que si un decorador reemplaza la función decorada por otra, debe copiar el __doc__ original a la nueva función. De Python 2.5, functools.wraps() se puede utilizar para crear funciones de decoración de buen comportamiento.

Referencias:

• Python Sphinx autodoc and decorated members

• http://sphinx.pocoo.org/ext/autodoc.html#directive-autoexception