Sto usando Sphinx per documentare il mio progetto python. Ho l'estensione autodoc abilitata e ho il seguente nei miei documenti.Come posso utilizzare l'estensione Autodoc di Sphinx per metodi privati?
.. autoclass:: ClassName
:members:
Il problema è che documenta solo il non-private methods nella classe. Come posso includere anche i metodi privati?
Hai provato a utilizzare un custom method per determinare se un membro deve essere incluso nella documentazione, utilizzando autodoc-skip-member?
Ecco un suggerimento: immagina che privato significhi "segreto".
Ecco perché Sphinx non li documenterà.
Se non si intende "segreto", prendere in considerazione la modifica dei loro nomi. Evitare di usare il nome di un singolo trattino principale in generale; non aiuta se non si ha un motivo per mantenere l'implementazione segreta.
Questo sembra tornare indietro a ciò che dice PEP-8 in privato. "In caso di dubbio, scegli un pubblico non pubblico" http://www.python.org/dev/peps/pep-0008/ – svrist
@svrist: Non indietro: è il punto esatto. Sfinge non documenterà non pubblico. Se si sceglie non pubblico, non si ottiene la documentazione automatica. Se vuoi documentazione, d'altra parte, non scegliere non pubblico. Qui, "dubbio" significa che hai una buona ragione per entrambi e non puoi decidere. Se non hai un buon motivo * per non pubblico, non hai nemmeno "dubbi". Rendilo pubblico a meno che tu non abbia una * buona * ragione per non-pubblica. –
Ma cosa succede se si utilizza Sphinx per la documentazione * internal *? –
No, privato significa privato per la classe e non deve essere utilizzato dall'API pubblica. Non intende significare il segreto e per quelli di noi che desiderano utilizzare la sfinge per la documentazione completa delle classi, escludendo metodi privati è piuttosto fastidioso.
La risposta precedente è corretta. Dovrai utilizzare un metodo personalizzato poiché Sphinx attualmente non supporta l'autodoc in combinazione con metodi privati.
Un modo per aggirare questo è forzare esplicitamente Sfinge a documentare membri privati. È possibile farlo aggiungendo automethod alla fine la documentazione livello di classe:
class SmokeMonster(object):
"""
A large smoke monster that protects the island.
"""
def __init__(self,speed):
"""
:param speed: Velocity in MPH of the smoke monster
:type speed: int
.. document private functions
.. automethod:: _evaporate
"""
self.speed = speed
def _evaporate(self):
"""
Removes the smoke monster from reality. Not to be called by client.
"""
pass
Esatto! Grazie mille per questo: o) –
Solo tieni presente che '.. document private functions' e' .. automethod :: _FUNC_NAME' devono essere posizionati ovunque tu voglia che l'output sia localizzato.Non devono essere nella funzione '__init __()' della classe correlata – dtlussier
grazie anche a livello di modulo per la funzione di modulo privato: IE '.. autofunction :: _my_private_module_function' nel modulo docstring e nel mio file' .rst'. Sfortunatamente ': membri privati:' non ha funzionato per funzioni private a livello di modulo. Penso che funzioni solo sulle classi. –
se si utilizza sfinge 1.1 o superiore, dal sito della documentazione sfinge a http://sphinx.pocoo.org/ext/autodoc.html,
:special-members:
:private-members:
Nota che puoi renderlo predefinito per tutte le classi usando ['autodoc_default_flags'] (http://sphinx.pocoo.org/ext/autodoc.html# confval-AutoDo c_default_flags) impostazione. –
Guardando apidoc code , siamo in grado di cambiare ciò che sfinge-apidoc generare impostare una variabile d'ambiente:
export SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance'
È inoltre possibile aggiungere questa configurazione nel tuo Makefile (i f tuo pacchetto utilizza uno):
docs:
rm -rf docs/api
SPHINX_APIDOC_OPTIONS='members,special-members,private-members,undoc-members,show-inheritance' sphinx-apidoc -o docs/api/ intellprice
$(MAKE) -C docs clean
$(MAKE) -C docs html
è possibile aggiungere questo al file di conf.py:
autodoc_default_flags = ['members', 'undoc-members', 'private-members', 'special-members', 'inherited-members', 'show-inheritance']
Sfinge ha recentemente aggiunto una caratteristica per questo: https://bitbucket.org/birkenfeld/sphinx/issue/176/provide-option-to-include-private-e –
@KevinHorn Sarebbe bello se * sphinx-apidoc * lo avesse pure – mlt