A la hora de elegir una herramienta para manejar la documentación, lo primero que hice fué revisitar viejos conocidos, en este caso Doxygen.
Doxygen como todos sabeis permite obtener documentación a partir del código. A través de comentarios que tienen una forma especial, se documenta directamente sobre el código que escribimos, y Doxygen saca toda la información posteriormente y la podemos obtener en diversos formatos, aunque por defecto genera html y pdf.
Tiene muchos detalles. Referencias cruzadas, índices, páginas aparte, código de ejemplo, diagramas con graphviz… Lo cierto es que sin apenas esfuerzo se obtiene una documentación muy amigable y si se programa teniendo en cuenta la documentación, el código es mucho más legible.
Doxygen por defecto no se lleva demasiado bien con Python. Primero, porque está programado para lenguajes que utilizan bloques cerrados entre llaves, y siendo Python un lenguaje sin ese azuquitar sintáctico, a veces se lía.
Otro gran defecto, es que los comentarios Doxygen se colocan justo encima de la declaración de la variable o función que se quiera documentar, mientras que Python provee su propio sistema de documentación integrado en el lenguaje mediante docstrings… que se ponen justo debajo de la declaración.
Llegados a ese punto, ¿no es un poco ridículo llevarle la contraria al lenguaje?. Si ya te provee un sistema para que pongas la documentación en docstrings accesibles en tiempo de ejecución e integradas, ¿debemos dejar de usarlas y pasarnos al bloque de comentarios sobre las funciones habitual de Java, Perl o C++?.
La respuesta es NO, y la ayuda necesaria la encontré en forma de un pequeño script llamado doxypy, que consiste en un filtro que se invoca desde Doxygen para que modifique el código python, extraiga comentarios y realice varios arreglos de manera que Doxygen lo trate de manera parecida a código Java.
¿Como usarlo?
- Bajamos Doxypy de su página
- Lo descomprimimos en el directorio donde tenemos el Doxyfile
- Modificamos la siguiente opción del Doxyfile que nos permite especificar el filtro:
FILTER_SOURCE_FILES = YES INPUT_FILTER = "python doxypy/doxypy.py"
Ojo que la ruta es relativa al fichero Doxyfile. Yo he renombrado el directorio doxypy-1.4 a doxypy a secas.
Se puede instalar en el sistema, pero yo prefiero tenerlo junto con el proyecto para poder ejecutarlo desde cualquier máquina cuando me lo baje del repositorio.
Adicionalmente podemos activar opciones específicas para Java, que se llevan bien con el código en Python, como son:
OPTIMIZE_OUTPUT_JAVA = YES
Esto último lo que hace es cambiar ciertas cosas de su representación típica en C++ a Java, que es más similar a Python, como por ejemplo la jerarquía de clases que pasaría de Padre::Hijo a Padre.Hijo.
También se avisa que para las docstrings de los módulos, que no se pillan por defecto, hay que introducir un @namespace en ellas con el nombre del módulo, y esta declaración hará el truco.
Espero que os sirva 
Hola!
Muy interesante, pero había oido por ahí que los pythonianos utilizaban cosas como epydoc o sphinx mucho más orientadas a generación automática de documentación en python. ¿Las descartaste?
Comentario por Fsero — marzo 11, 2010 @ 12:37 am
Tengo instalado también sphinx, pero esas dos herramientas no las uso porque son otro rollo.
epydoc es como un javadoc pero para python. Osea feo y poco más que un listado de funciones, sin páginas, ejemplos y otras gabelas.
sphinx fundamentalmente la descarté porque NO estaba orientada a la generación automática a partir del código. Lo hace, pero lo tiene como una opción escondida. El resto de la documentación hay que escribirla a pezuña y usando un formato basado en texto plano que habría que aprender… demasiado trabajo, y además todo el curro de las docstrings en el código para casi nada.
Gracias por el comentario
Comentario por Javier Santacruz López-Cepero — marzo 11, 2010 @ 12:41 am
Enhorabuena por el accésit ; )
Comentario por emijrp — marzo 17, 2010 @ 4:18 pm