Ometti (o formatta) il valore di una variabile quando si documenta con Sfinge

Question

Attualmente sto documentando un intero modulo con autodoc. Tuttavia, definisco diverse variabili a livello di modulo che contengono lunghe liste o dict. Sono inclusi nella documentazione insieme ai valori, e i valori non sono formattati, quindi sembra un caos di 10 righe. Quello che voglio è che la docstring di quelle variabili sia inclusa, ma che i valori siano omessi o quantomeno formattati in modo appropriato.

Ho cercato di escludere la variabile da automodule direttiva e aggiungerlo come quella:

.. automodule:: foo.bar 
    :members: 
    :exclude-members: longstuff 

    .. py:data:: longstuff 

Ciò ha determinato che solo il nome della variabile è stata inclusa, considerando che sia la docstring e il valore della longstuff non erano presente nella documantazione.

Come è possibile mantenere la docstring e sbarazzarsi del valore (o averlo formattato correttamente) allo stesso tempo? Grazie in anticipo.

Answer 1

Non c'è alcuna impostazione di configurazione semplice per omettere i valori delle variabili di livello modulo nell'output. Ma puoi farlo modificando il metodo DataDocumenter.add_directive_header() in autodoc.py. La linea fondamentale che il metodo è

self.add_line(u' :annotation: = ' + objrepr, '<autodoc>') 

dove objrepr è il valore.

La seguente patch scimmia aggiunto conf.py opere per me:

from sphinx.ext.autodoc import ModuleLevelDocumenter, DataDocumenter 

def add_directive_header(self, sig): 
    ModuleLevelDocumenter.add_directive_header(self, sig) 
    # Rest of original method ignored 

DataDocumenter.add_directive_header = add_directive_header