Come posso generare documentazione per un setter di proprietà Python usando Sphinx?

Ho una classe Python qualcosa di simile a quanto segue, con docstring destinati ad essere convertiti in documenti da Sphinx:Come posso generare documentazione per un setter di proprietà Python usando Sphinx?

class Direction(object): 
    """ 
    A direction in which movement can be made. 
    """ 
    def __init__(self): 
     self._name = None 

    @property 
    def name(self): 
     """ 
     The unique name of the direction. 

     :return: The direction name 
     :rtype: string 
     """ 
     return self._name 

    @name.setter 
    def name(self, value): 
     """ 
     Sets the direction name. 

     :param string value: The direction name 
     """ 
     self._name = value

L'uscita Sfinge sembra qualcosa di simile:

classeDirezione (nome) Una direzione in cui è possibile effettuare il movimento.

nome Il nome univoco della direzione.

Returns: Il nome direzione

Tipo ritorno: stringa

che va bene per quanto si va, ma è da notare la completa assenza di qualsiasi informazione circa il setter name.

C'è un modo per ottenere Sphinx per generare documentazione per il setter di proprietà?

fonte

2013-07-04 Matthew Murdoch

Sembra che abbia più senso documentare qualsiasi comportamento specifico di get/set nella documentazione getter se è lì che Sphinx lo cerca. La documentazione per il setter qui è fondamentalmente superflua: è una proprietà, quindi ovviamente imposta il valore, e anche la documentazione del parametro è inutile perché ogni setter richiede lo stesso argomento, e il setter non verrà effettivamente chiamato esplicitamente. Il comportamento speciale di get/set è in realtà una caratteristica della proprietà nel suo insieme. Il punto delle proprietà è che vi si accede tramite un singolo nome di attributo, non chiamate di funzione get/set separate. – BrenBarn

@BrenBarn Posso certamente farlo se è quello che Sphinx si aspetta. Tuttavia, la documentazione generata in realtà non indica che si tratta di una proprietà e non sono sicuro di come posso usare i tag ': param:', ': return:' e ': rtype:' per chiarirlo? –

@MatthewMurdoch, Sphinx documenta il getter senza usare '()'. Questo, insieme alla docstring combinata, dovrebbe aiutare l'utente a capire che si tratta di una proprietà. –

La sfinge ignora le docstring sui servizi di proprietà, pertanto tutta la documentazione relativa a una proprietà deve essere nel metodo @property.

Mentre Sphinx comprende determinati tag specifici (ad esempio :param ...:) accetta qualsiasi tag personalizzato e li renderà come etichette per il testo che li segue.

Quindi qualcosa come il seguente renderà la documentazione in modo ragionevole (getter, setter e type può essere modificato in qualsiasi altro testo, se necessario).

@property 
def name(self): 
    """ 
    The unique name of the direction. 

    :getter: Returns this direction's name 
    :setter: Sets this direction's name 
    :type: string 
    """ 
    return self._name

La documentazione generata simile a questa:

classeDirezione (nome) una direzione in cui movimento può essere fatto.

nome Il nome univoco della direzione.

Getter: restituisce il nome di questa direzione

Setter: Imposta il nome di questa direzione

Tipo: stringa

T grazie a @BrenBarm e @ A-B-B per avermi indirizzato nella direzione di questa soluzione.

fonte

2013-07-08 08:28:59

Come posso generare documentazione per un setter di proprietà Python usando Sphinx?

risposta

Problemi correlati