In Sphinx, c'è un modo per documentare i parametri e dichiararli?

Question

preferisco documentare ogni parametro (se necessario) sulla stessa linea in cui dichiaro il parametro al fine di applicare D.R.Y.

Se ho il codice come questo:

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    ... 

Come posso evitare di ripetere la parametri nella stringa doc e mantengono le spiegazioni dei parametri?

voglio evitare:

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    '''Foo does whatever. 

    * flab_nickers - a series of under garments to process 
    * needs_pressing - Whether the list of garments should all be pressed. 
     [Default False.] 

Questo è possibile in Python 2.6 o Python 3 con una sorta di manipolazione decoratore? C'è un altro modo?

Answer 1

Lo farei.

A partire da questo codice.

def foo(
     flab_nickers, # a series of under garments to process 
     has_polka_dots=False, 
     needs_pressing=False # Whether the list of garments should all be pressed 
    ): 
    ... 

avrei scritto un parser che afferra le definizioni dei parametri funzione e costruisce il seguente:

def foo(
     flab_nickers, 
     has_polka_dots=False, 
     needs_pressing=False, 
    ): 
    """foo 

    :param flab_nickers: a series of under garments to process 
    :type flab_nickers: list or tuple 
    :param has_polka_dots: default False 
    :type has_polka_dots: bool 
    :param needs_pressing: default False, Whether the list of garments should all be pressed 
    :type needs_pressing: bool 
    """ 
    ... 

Ecco alcune elaborazioni regex abbastanza straight-forward dei modelli di vari argomenti stringa di compilare il modello di documentazione .

Un sacco di buoni IDE Python (ad esempio PyCharm) comprendono la notazione Sphinx predefinita param e persino flag var/metodi nell'ambito che IDE ritiene non conforme al tipo dichiarato.

Annotare la virgola aggiuntiva nel codice; questo è solo per rendere le cose coerenti. Non fa male, e potrebbe semplificare le cose in futuro.

È inoltre possibile provare e utilizzare il compilatore Python per ottenere un albero di analisi, modificarlo ed emettere il codice di aggiornamento. L'ho fatto per altri linguaggi (non Python), quindi ne conosco un po ', ma non so quanto sia supportato in Python.

Inoltre, questa è una trasformazione una tantum.

I commenti originali in-line nella definizione della funzione non seguono realmente DRY perché si tratta di un commento, in un linguaggio informale, e inutilizzabile con strumenti diversi ma sofisticati.

I commenti di Sfinge sono più vicini a DRY perché sono nel linguaggio di marcatura RST, rendendoli molto più facili da elaborare utilizzando normali strumenti di analisi del testo in docutils.

È ASCIUTTO solo se gli strumenti possono farne uso.

Link utili: https://pythonhosted.org/an_example_pypi_project/sphinx.html#function-definitions http://sphinx-doc.org/domains.html#id1

Answer 2

Non si può farlo senza un preprocessore, come commenti non esistono per Python una volta che la sorgente è stato compilato. Per evitare di ripetere te stesso, rimuovere i commenti e documentare i parametri solo nella docstring, questo è il modo standard per documentare i tuoi argomenti.

Answer 3

annotazioni hanno lo scopo di affrontare in parte questo problema in Python 3:

http://www.python.org/dev/peps/pep-3107/

non sono sicuro se c'è stato alcun lavoro in applicazione di questi per Sfinge ancora.