¿Cómo documentar un proyecto de Python?

Question

Estoy programando una nueva biblioteca de Python, que necesita una buena documentación. ¿Cuáles son buenas formas de documentar una biblioteca de este tipo? Yo preferiría un método que genere una documentación completa en html.

Answer 1

Usar docstrings en todas partes es el primer paso. Luego puede usar cualquiera de varias herramientas de generación de documentación de python para generar documentación de calidad. Es lo que hace python.org, usando Sphinx.

Pero el uso de cadenas de documentación también tiene el beneficio adicional de ser útil para los programadores justo en el intérprete así:

>>> 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. 

Todo esto viene de la cadena de documentación de la función interna dir(), y se pone bastante impreso-bien a través de la función integrada help().