Re: [Python-es] Documentar código con docstrings

El día 3 de noviembre de 2009 09:24, Cesar Ortiz
<[email protected]> escribió:

> Estaba escribiendo unas 'guidelines' para python (sin inventar nada, claro..
> básicamente siguiendo el PEP 8) y hay un punto sobre el que no encuentro
> algo que me convenza.
> Anteriormente he usado epydoc para generar la documentación (parece que este
> proyecto está un poco parado, ¿puede ser?) pero estaba por la labor de algo
> mas pythoniano....
>
> La cuestión es que no encuentro una especificación que me convenza; es todo
> muy genérico. Y preferiría no tenermelo que inventar...
> ¿Sabeis de alguna especificación que merezca la pena?

No sé si te entiendo bien. ¿Estás buscando un documentador de APIs
(epydoc) o estás buscando algún estilo para documentar código (PEP8)?

Para documentar APIs, además de epydoc, se usa bastante doxygen
(http://www.doxygen.org).

Pero en estos momentos toda documentación python se está orientando
hacia "sphinx" (http://sphinx.pocoo.org/). Sphinx posee una serie de
extensiones que permiten verdadera "programación literaria" (autodoc,
doctest, graphviz,...).

Estas extensiones son las que mejor te orientarán sobre cómo deberías
documentar el código. Como mínimo deberías incluir pruebas "doctest"
(módulo estándar), muy útiles tanto para documentar como para realizar
tests funcionales.



PD: "Programación Literaria": http://www.literateprogramming.com/
_______________________________________________
Lista de correo Python-es 
http://listas.aditel.org/listinfo/python-es
FAQ: http://listas.aditel.org/faqpyes