Come documentare un progetto Python?

Question

Sto programmando una nuova libreria Python, che richiede una buona documentazione. Quali sono i buoni modi per documentare una tale libreria? Preferirei un metodo che genera una documentazione completa in html.

Answer 1

L'utilizzo di docstrings ovunque è il primo passo. Quindi è possibile utilizzare uno qualsiasi degli strumenti di generazione di documentazione Python per generare documentazione di qualità. È ciò che python.org fa, usando Sphinx.

Ma usando docstring ha anche il vantaggio aggiuntivo di essere utile per i programmatori proprio nel interprete così:

>>> help(dir) 
Help on built-in function dir in module __builtin__: 

dir(...) 
    dir([object]) -> list of strings 

    If called without an argument, return the names in the current scope. 
    Else, return an alphabetized list of names comprising (some of) the attributes 
    of the given object, and of attributes reachable from it. 
    If the object supplies a method named __dir__, it will be used; otherwise 
    the default dir() logic is used and returns: 
     for a module object: the module's attributes. 
     for a class object: its attributes, and recursively the attributes 
     of its bases. 
     for any other object: its attributes, its class's attributes, and 
     recursively the attributes of its class's base classes. 

Tutto questo deriva dal docstring della funzione built-dir(), e diventa piuttosto-stampato bene tramite la funzione integrata help().