valori Sphinx per gli attributi riportati come Nessuno

Question

Quando uso Sfinge autodoc per documentare una classe, i valori per gli attributi vengono sempre segnalati, (come si dice dovrebbe here, sotto # 437), ma sempre come "= None"

Attribute = None 
    Some Documentation 

ho includerlo come

.. autoclass:: core.SomeClass 
    :members: 

E il mio codice è simile

class SomeClass(object): 
    def __init__(self): 
     self.attribute = "value" #: Some Documentation 

Esiste un modo per rendere "= None" il valore reale o farlo scomparire?

Answer 1

Sono sicuro che questo ha a che fare con il fatto che il tuo attributo è un attributo di istanza. Non ottiene un valore fino a quando la classe non viene istanziata. Sfinge importa i moduli per ispezionarli, ma non istanzia nessuna classe.

Quindi il "valore reale" non è noto a Sphinx e viene emesso None. Non penso che tu possa farla andare via facilmente (ma suppongo che tutto sia possibile se sei pronto a patchare il codice sorgente di Sphinx ...). Se non ti piace, puoi invece documentare gli attributi nella docstring della classe.

Gli attributi di classe documentati utilizzando lo stesso schema di marcatura (described here) visualizzano i loro valori nell'output di rendering. Ma non c'è una chiara indicazione che renda facile per il lettore distinguere tra attributi di classe e istanza. Forse la Sfinge potrebbe essere un po 'più utile qui.

Answer 2

Ci sarà un'opzione :annotation: (vedere pull-request) nella prossima versione 1.2 di sfinge (e nella seconda beta).

Per autodata/autoattribute è quindi possibile forzare un valore specifico o sopprimerlo. Quindi, al fine di stampare alcun valore per l'attributo che si metterebbe:

.. autoclass:: core.SomeClass 

    .. autoattribute:: attribute 
     :annotation: 

Attualmente funziona solo con autodata/autoattribute direttamente e non in modo ricorsivo con automodule/autoclass.

Answer 3

Questo sembra essere ancora un problema. Ho lavorato intorno ad esso con:

class ValueDoc: 

    def __init__(self, text): 
     self.text = text 

    def __repr__(self): 
     return self.text 

e quindi definire l'attributo a livello di classe come:

#: documentation for foo 
foo = ValueDoc('text to show up after =') 

Answer 4

non ero in grado di ottenere le annotazioni di lavoro per gli attributi di istanza. Ho scelto di nascondere solo i valori degli attributi nel mio tema.

Esempio html

<dl class="attribute"> 
    <dt> 
    <code class="descName">Attribute</code> 
    <em class="property"> = None</em> 
    </dt> 
</dl> 

Tema CSS per nascondere = None

dd dl.attribute em.property { display: none } 

Answer 5

Per la versione corrente di Sfinge, si può mettere un monkeypatch nel conf.py del progetto che risolve questo problema:

from sphinx.ext.autodoc import (
    ClassLevelDocumenter, InstanceAttributeDocumenter) 

def iad_add_directive_header(self, sig): 
    ClassLevelDocumenter.add_directive_header(self, sig) 

InstanceAttributeDocumenter.add_directive_header = iad_add_directive_header 

Questo è discusso in Sphinx issue #2044