Libertonia
Portada · Todo · Software Libre · Desarrolladores · Comunidad · Internet · Tecnología · Meta · Diarios
Documentando código Python: pydoc

Programación
Por Ariel
departamento porque-las-serpientes-molan , Sección Desarrolladores
Puesto a las Wed Jul 23rd, 2003 at 11:36:40 AM CET

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.


Un saludo

http://milugar.doesntexist.org

< Llega 2.6.0-test (15 comments) | Linux y la "mala memoria" (29 comments) >
Enlaces Relacionados
· escomposlinux.org
· esta encuesta
· pydoc
· este archivo
· el diagrama UML
· el código
· aquí
· documentación en html
· aquí[2]
· docutils
· texto estructurado
· http://milugar.doesntexist.org
· More on Programación
· Also by Ariel

Menu
· crear cuenta
· FAQ
· búsqueda
· Fuentes de Noticias

Login
Nueva cuenta
Usuario:
Contraseña:

Ver: Modo: Orden:
Documentando código Python: pydoc | 3 comentarios (1 temáticos, 2 editoriales, 0 ocultos)
Doxygen y docutils (3.00 / 1) (#3)
por ridiculum a las Fri Aug 1st, 2003 at 07:56:08 PM CET
(Información Usuario)

Estoy mirando docutils para ver como genera la documentacion, y parece que es capaz de generar Latex, cosa bastante útil para mi, pero no he podido ver ningún ejemplo en la web de docutils. ¿Lo hay? ¿Es comparable docutils a doxygen? ¿Tendra doxygen soporte para python algun día?



 
Documentando código Python: pydoc | 3 comentarios (1 temáticos, 2 editoriales, 0 ocultos)
Ver: Modo: Orden:

ecol Logo Powered by Scoop
Todas las Marcas Registradas y copyrights de esta página son propiedad de sus respectivos dueños.
Los comentarios son propiedad del que los escribe.
Los iconos de las noticias y el logotipo son propiedad de Javier Malonda.
El Resto © 2002 Escomposlinux.org y aledaños.

Puedes sindicar los contenidos de libertonia en formato RSS 1.0 y RDF 0.9. También se puede sindicar la cola de envíos pendientes de moderación.

El proyecto escomposlinux.org está dedicado a la memoria de tas

crear cuenta | faq | búsqueda