Web BizarroWeb Bizarro

Suscríbete a nuestro Newsletter

X

Únete a nuestra lista de correos para recibir semanalmente actualizaciones de nuestro contenido.

Sphinx una completa herramienta para documentar

Sphinx una completa herramienta para documentar 18.AUG.15

Alvaro José Rios Ch
Fundador WebBizarro

La documentación en el código es muy importante, no solo cuando piensas distribuirlo sino en todo momento ya que te permite conocer lo que hace cada pieza de código que escribiste y para que la escribiste, por eso documentar el código debería ser una practica constante.

Sphinx es una herramienta originalmente creada para documentar código en python pero que gracias a si potencia ha sido extendida para la comunidad para muchos otros lenguajes, como PHP, C/C++, JavaScript, Ruby e incluso Matlab y permite generar la documentación en múltiples lenguajes.

La herramienta requiere algo de configuración sin embargo todo esta muy bien detallado y no es un gran problema, para generar la documentación se usan los comentarios en las funciones pero además se puede extender con archivos de texto enriquecidos para no colocar encabezados y textos introductorios en el código.

Existe un pequeño lenguaje similar al markdown que le permite a la herramienta crear la documentación, hay formatos para tablas, urls, imágenes, listas y más. Pero pueden ver un ejemplo completo aquí.

Es una herramienta muy completa, útil y sin ningún desperdicio, además que tiene un montón de extensiones con lo que puedes agregar más funcionalidad como agregar hojas de excel, gráficos de google chart o mapas de google maps, así que no hay excusa para no comenzar a crear documentación profesional en todos tus proyectos.