Come posso produrre una documentazione simile a numpy?

Question

Sto lavorando molto con Spyder e l'ispettore degli oggetti, che trovo piuttosto comodo come funzione di aiuto istantaneo. Alcuni moduli sembrano beneficiare molto bene di questa funzione. Per esempio una funzione NumPy piuttosto semplice (numpy.absolute) produce il seguente vista nella finestra di ispezione oggetto:

Voglio sapere, come posso scrivere i miei propri moduli in modo tale, che un tale una bella vista viene prodotta quando chiamo le mie funzioni in spyder.

Answer 1

Per rendere la tua documentazione altrettanto gradevole con quella numpy, è necessario seguire lo standard NumpyDoc. Supponiamo di avere una funzione chiamata func con due argomenti come questo:

def func(arg1, arg2): 
    return True 

Per aggiungere la documentazione ad esso è necessario scrivere una stringa multilinea sotto la sua definizione (chiamato nel mondo Python docstring), come questo

def func(arg1, arg2): 
    """Summary line. 

    Extended description of function. 

    Parameters 
    ---------- 
    arg1 : int 
     Description of arg1 
    arg2 : str 
     Description of arg2 

    Returns 
    ------- 
    bool 
     Description of return value 

    Examples 
    -------- 
    >>> func(1, "a") 
    True 
    """ 
    return True 

Ciò che Spyder fa è che prende questa descrizione in testo semplice, lo analizza e lo restituisce come html e infine lo mostra nell'Object Inspector.

Per vederla basta chiamare func da qualche altra parte nel codice e premere Ctrl + i accanto ad essa, in questo modo:

func<Ctrl+i>(1, "a") 

Ciò è dimostrato anche automaticamente quando si scrive un parentesi sinistra accanto a func.

Answer 2

Se avete il vostro progetto Python (o file) già documentato con un altro stile (come reStructuredText o Epytext) o meno documentati, è possibile generare/convertire i docstrings in NumpyDoc stile utilizzando Pyment:

pyment -o numpydoc /my/python/project 

Nota che il comando precedente, eseguito dopo Pyment installato, genererà patch che dovrebbero essere applicate al tuo codice.

Una volta che il progetto è documentato utilizzando lo stile Numpydoc, è possibile utilizzare il Sphinx extension per generare il vostro bello documentazione stile leggibile NumpyDoc!