Utilizzo di spodx autodoc per un file favoloso

Question

È possibile utilizzare Spodx autodoc per generare documentazione per il mio file, dalla docstring della funzione?

E.g. per un fabfile contenente un compito setup_development ho provato:

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

Ma nulla viene generato.

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

sono stato in grado di produrre una documentazione completa con la firma funzione conservata tramite decorator_apply ricetta found in the documentation per il modulo 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 

Questa è la semplice fonte di riposo che ho usato:

.. automodule:: myfabfile 
    :members: 

Alcuni commenti:

La risposta presentata dal shahjapan spiega come preservare la docstring nel caso generale, ma lo fa non affrontare il fatto che il decoratore @task è definito in una libreria esterna.

In ogni caso, si scopre che la docstring viene conservata automaticamente per le funzioni decorate con @task. Quello che segue è nel metodo della classe di tessuto tasks.WrappedCallableTask__init__:

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

Così che funziona già così com'è (un esplicito .. autofunction:: è necessario). Per garantire che anche la firma della funzione venga preservata, è possibile utilizzare il modulo decorator come mostrato sopra.

---

Aggiornamento

L'utilizzo del modulo decorator rompe le cose nel funzionamento di tessuto (vedi commento). Quindi, dopo tutto, potrebbe non essere fattibile. Come alternativa suggerisco il seguente markup modificato:

.. automodule:: myfabfile2 
    :members: 

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

Ciò significa che è necessario includere la firma della funzione completa. Questo è anche ciò che è suggerito nella documentazione di Sphinx (vedi "This is useful if the signature from the method is hidden by a decorator.").

Answer 2

sua perché hai decoratore applicato sulla vostra funzione setup_development

è necessario aggiornare la funzione task con functools.wraps come sotto,

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 

Se funzioni o metodi decorati da documenti, tenere presente che autodoc recupera le sue docstring importando il modulo e ispezionando l'attributo __doc__ della funzione o metodo specificato.

Ciò significa che se un decoratore sostituisce la funzione decorata con un'altra, deve copiare l'originale __doc__ nella nuova funzione. Da Python 2.5, functools.wraps() può essere utilizzato per creare funzioni di decorazione ben educate.

Riferimenti:

• Python Sphinx autodoc and decorated members

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