Buscando mejorar la documentación de pygame

[hugoruscitti]

Saludos, hace unos días atrás Julian envió un correo a la lista
de pygame (en inglés) para sugerir un nuevo sistema de
documentación.

Actualmente la documentación de pygame se almacena en
un wiki con un formato muy propio, lo que dificulta un
poco hacerle cambios y claro, búsquedas, exportaciones etc:

http://www.pygame.org/docs/

Julian sugiere algo que me parece interesante, utilizar el
sistema de documentación Sphinx, que muchos proyectos
python lo están utilizando y ofrece varias ventajas, entre
las que se mecionan:

- Tiene un sistema de plugins que permite agregar funcionalidad
para hacer casi cualquier cosa.
- Su sintaxis es sencilla, dado que utiliza restructured text, algo
a lo que están bastante familiarizados los programadores de
python y esto motiva las contribuciones.
- Permite exportar toda la documentación en formatos como
html o pdf fácilmente.

Por eso, Julian se puso a escribir una versión alternativa
de la documentación de pygame con la intensión de que
vuelva la documentación oficial algún día. Y a mí, como
me pareció una buena idea me contacté con él y estoy
por realizar algunos aportes ahí.

Este es el resultado que se tiene hasta ahora:

http://pygameweb.no-ip.org/media2/newdoc/modindex.html

Me gustaría saber que les parece a ustedes, ¿hay algo de
la documentación que vean mejorable?.

Por ejemplo, yo le conté a julian que podríamos agregar
imágenes como ejemplo de algunas funciones y le pareció
una buena idea. ¿que les parece a ustedes?.

¿alguna idea?.

[hugoruscitti]

ah, otra cosa que había olvidado: Si la documentación de
pygame oficial se pasa a sphinx, a nosotros nos va a resultar
mucho mas sencillo actualizar nuestra versión 1.8 de la
versión en español a 1.9 ...

de hecho, se podría integrar a la misma biblioteca y sería
un aporte bastante interesante...

[endaramiz]

Parece una buena idea.

No sé si aun no se ha hecho por falta de tiempo, pero yo echo en falta los índices de métodos de los módulo que tenían una pequeña explicación y que si les clicas "te llevan" a la parte de la pagina donde está situado el método.

Lo de las imágenes puede ir bien en ocasiones. Pero si se alarga mucho la página, haría más falta hacer lo que comentaba antes.


Saludos.