[pyar] Docstring para módulo/script: sugerencias?

[Wil Alvarez]

El 19 de noviembre de 2012 15:28, Ezequiel Garcia
<elezegarcia en gmail.com>escribió:

> Buenas,
>
> Estoy documentando un script más o menos largo (~1000 lineas)
> que sirve para instrumentar un sistema [1].
>
> Se espera que (con suerte) el script se incluya como parte del sistema
> y por simplicidad quisiera agregar toda la documentación que tengo
> *dentro* del script mismo.
>
> Mi primer opción (por ser un programador desorientado en python)
> fue ponerlo todo como un gran comentario al comienzo del script.
>
> Pero después pensé: "mmm... esto huele mal..." y ahora estoy
> empezando a ponerlo como docstrings para ver como queda.
>
> Obviamente, ya sé que hay toneladas de cosas escritas al respecto,
> pero quería saber que opinaban uds. de todos modos.
>
> ¿Hay un estilo particular para separar temas y párrafos?
>
> Gracias y saludos!
>
>     Ezequiel
>
> [1] Si a alguien le interesa, lo cual es dudoso, el script es este:
> https://github.com/ezequielgarcia/trace_analyze
> A pesar de mis muchos esfuerzos, el script es ilegible,
> así que no digan que no les dije.
> _______________________________________________
> pyar mailing list pyar en python.org.ar
> http://listas.python.org.ar/listinfo/pyar
>
> PyAr - Python Argentina - Sitio web: http://www.python.org.ar/
>
> La lista de PyAr esta Hosteada en USLA - Usuarios de Software Libre de
> Argentina - http://www.usla.org.ar


Ezequiel,

Te recomiendo que le des un vistazo a Sphinx [1], es fácil de usar, te
permite definir una estructura bastante clara/simple y además tengo
entendido que es una de las herramientas más usadas para ese fin. Yo lo
estoy usando para libturpial y funciona de maravillas. Puedes empezar con
este breve tutorial [2].

Saludos

[1] http://sphinx-doc.org/
[2] http://packages.python.org/an_example_pypi_project/sphinx.html

-- 
“Yo construyo Soberanía, uso Software Libre”
Wil Alvarez
Linux Counter #415026
http://damncorner.blogspot.com
------------ próxima parte ------------
Se ha borrado un adjunto en formato HTML...
URL: <http://listas.python.org.ar/pipermail/pyar/attachments/20121119/26ba901a/attachment.html>