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

[Cesar Ortiz]

Necesito formalizar como vamos a documentar las APIs.
Como ya decía había usado epydoc. Pero como bien dices parece que ahora van
mas los tiros hacia sphinx... Pero no lo veo tan claro como con epydoc, de
ahí la pregunta...

Por otro lado la última versión estable de epydoc es de Enero del 2008, lo
cual da a pensar que el proyecto está un poco parado.


2009/11/3 Chema Cortes <pych3m4 en gmail.com>

> El día 3 de noviembre de 2009 09:24, Cesar Ortiz
> <cesar.ortiz en gmail.com> 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
>
_______________________________________________
Lista de correo Python-es 
http://listas.aditel.org/listinfo/python-es
FAQ: http://listas.aditel.org/faqpyes