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

[Ezequiel Garcia]

2012/11/19 Juan Carlos Ojeda <juancarlospaco en gmail.com>:
> 2012/11/19 Ezequiel Garcia <elezegarcia en gmail.com>
>>
>> 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.
>
>
>
> http://www.python.org/dev/peps/pep-0287/   ?
>

Gracias! Tomé nota:

1. Se puede documentar en texto plano
2. Se recomienda usar reStructuredText

Gracias!

    Ezequiel