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

[Manuel Jesús Recena Soto]

Hola Cesar:

El día 3 de noviembre de 2009 10:48, Cesar Ortiz
<cesar.ortiz en gmail.com> escribió:
> 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...

Sphinx no lo he usado pero me lo han recomendado recientemente. Sí que
he usado mucho doxygen. Lo bueno en este caso es que estás optando por
una herramienta que te servirá para múltiples lenguajes. Si además
usas integración continua, podrás tener actualizada tu documentación y
que los desarrolladores accedan a ella cómodamente.

Un saludo

>
> 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
>



-- 
Manuel J. Recena Soto
* www.manuelrecena.com[/blog]
* recena en us.es, recena en gmail.com
* +34 609710280 (ES)
_______________________________________________
Lista de correo Python-es 
http://listas.aditel.org/listinfo/python-es
FAQ: http://listas.aditel.org/faqpyes