Cosa si usa per "__docformat__" in Python?

Question

mi sono stati codifica per circa un anno in Python ed io siamo appena imbattersi in qualche codice in un Theano tutorial che dichiara una variabile nella parte superiore del file:

__docformat__ = 'restructedtext en' 

Cercando su internet ha prodotto this documentazione PEP. Anche se ancora non spiega chiaramente quando/perché vorresti specificare questa variabile.

Devo dichiararlo in cima a tutto il mio codice Python?

Answer 1

Il punto di __docformat__ consiste nel consentire agli strumenti del generatore di documentazione python come epydoc di sapere come analizzare correttamente la documentazione del modulo (ad esempio quale linguaggio di markup prevedere).

Dal epydoc docs:

Per specificare il linguaggio di marcatura per un modulo, è necessario definire una stringa a livello di modulo __docformat__ variabile, contenente il nome del linguaggio di markup del modulo. Il nome della lingua di marcatura può facoltativamente essere seguito da un codice di lingua (come en per l'inglese). Convenzionalmente, la definizione della variabile __docformat__ segue immediatamente docstring del modulo

Tuttavia, molti strumenti come epydoc supportano anche specificare il linguaggio di marcatura tramite riga di comando (ad es epydoc --docformat restructuredtext), quindi non c'è alcuna necessità rigorosa per includere la docformat. È più semplicemente qualunque sia la convenzione di codifica per il tuo progetto o organizzazione.