descrizione multilinea di una descrizione dei parametri in python docstring

Question

Quindi, reStructuredText è the recommended way per Python codice documentazione, se si tenta già abbastanza difficile, si può find in the sphinx documentation come normalizzare la documentazione firma funzione. Tutti gli esempi forniti sono a linea singola, ma cosa succede se la descrizione di un parametro è multi-linea come il seguente ?

def f(a, b): 
    """ Does something with a and b 

    :param a: something simple 
    :param b: well, it's not something simple, so it may require more than eighty 
       chars 
    """ 

Qual è la sintassi/convenzione per questo? Dovrei indentare o no? interromperà il rendering di reSTructuredText?

Answer 1

sembra che se si trattino da almeno un livello relativo al: param: direttiva, non si rompe il rendering reStructuredText. Personalmente, preferisco allineare tutte le altre linee alla prima riga descrittiva di quel parametro. Nota, che reST ignorerà anche le nuove linee e renderà il tuo testo senza le interruzioni di riga.

Purtroppo, non sono riuscito a trovare alcuna fonte che menzionasse questo problema o fornisse un esempio di una linea multipla: param: descrizione.

Answer 2

semplicemente newline dove si desidera interrompere la linea.

def f(a, b): 
    """ Does something with a and b 

    :param a: something simple 
    :param b: well, it's not something simple, 
       so it may require more than eighty 
       chars 
    """ 

Answer 3

Sì, sembra che qualsiasi comodo per i lavori di indentazione per Sphinx e pep8 non discute. Inoltre, se non si vuole descrizione di essere più righe nella documentazione prodotta è possibile utilizzare Python linea tradizionale breakes con \:

def f(a, b): 
    """ Does something with a and b 

    :param a: something simple 
    :param b: well, it's not something simple, so it may require more \ 
       than eighty chars 
    """