Después del éxito de Python y Zope en esta encuesta, y de las diferente formas que se comentaron de documentar código php, aquí viene el contrapunto en Python.

Si has programado en Java alguna vez, habrás utilizado javadoc para documentar tu código. En Python disponemos de una herramienta similar, muy fácil de usar, capaz de producir salidas en html, e incluso correr un pequeño servidor web para acceder a toda la documentación.

La documentación es un aspecto fundamental en programación. No sólo es necesario que las APIs, los lenguajes o los módulos que utilicemos estén bien documentados, sino que es vital que nosotros documentemos correctamente nuestro propio código para que otras personas puedan entenderlo, y para que su mantenimiento resulte más fácil.

Como hemos comentado, Java viene con una utilidad que genera automáticamente la documentación de su código. Python no es menos y de serie (recordemos el lema batteries included) viene con pydoc.

Como todo en Python, pydoc es muy fácil de utilizar. Un simple

pydoc -w <nombre>

generará la documentación en html de <nombre>.

Esto es muy frío, veamos un ejemplo:

pydoc -w ftplib
wrote ftplib.html

y generará este archivo. Todo esto es muy bonito pero, ¿cómo documento yo mi código?

Es fácil. Si has leido el tutorial de Python, te sonarán las cadenas de documentación. Éstas pueden acompañar funciones, clases y módulos. Un ejemplillo:

def prueba():
   """Esto es una cadena de documentacion"""
   return

pydoc utiliza estas cadenas para construir la documentación, así que la calidad de ésta dependerá de lo detalladas que sean estas cadenas.

Mostremos un ejemplo de código que no pertenezca a la distribución estándar. Se trata de un módulo que modela la clase Baraja y otras. Para que no andes perdido, puedes ver el diagrama UML. Con este diagrama, implementamos las clases. Aquí está el código, y podrás verlo más cómodamente aquí.

Bien, ahora ejecutamos

pydoc -w baraja
wrote baraja.html

y ya tenemos nuestra documentación en html

Si ejecutamos pydoc sin parámetros veremos la documentación del módulo en cuestión en formato similar a las páginas de manual Unix. Es lo mismo que si ejecutas help(<nombre>) en el intérprete interactivo.

pydoc puede lanzar un pequeño servidor web en el que navegar por toda la documentación. La sintaxis para lanzarlo es:

pydoc -p <puerto>

Ahora sólo tienes que abrir tu navegador y poner la dirección http://localhost:<puerto> y tendrás acceso a la documentación de todos los módulos.

También se dispone de un pequeño programa con interfaz gráfica escrito en TKinter que permite buscar en la documentación. Para iniciarlo, basta con

pydoc -g

y ya estará listo para buscar en la documentación.

Para más información consulta la documentación de pydoc. Incluso puedes verlo en acción aquí.

Como alternativa, puedes encontrar docutils. Aunque no lo he utilizado parece un proyecto que goza de buena salud. Además aprovecha el texto estructurado en las cadenas de documentación.