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

[Ezequiel Garcia]

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.