sábado, 21 de febrero de 2015

Generar documentación en Python con Sphinx


Que pereza nos da hacer documentación, nos pone de mal humor...

Sphinx es una herramienta que hace que sea fácil crear documentación inteligente y sobre luzca agradable y bien organizada. Esta herramienta fue creada por Georg Brandl y con licencia BSD.

Yo que vengo de Java he usado javadoc y tambien el plugin de maven que genera un sitio que tiene documentación oriunda del código.

Entre las características de Sphinx:

  • Maneja diferentes tipos de formato de salida: HTML (incluyendo Windows HTML Help), LaTeX (para versiones en PDF para imprimir), ePub, Texinfo, páginas de manual, de texto sin formato.
  • Amplias referencias cruzadas: Marcado semántico y vínculos automáticos para funciones, clases, citas, términos del glosario y piezas similares de información.
  • Estructura jerárquica: Definición sencilla de un árbol de documentos, con enlaces automáticos a padres e hijos
  • Índices automáticos: Índice general, así como los índices de los módulos específicos del idioma del código: resaltado automático utilizando el resaltador Pygments.
  • Extensiones: Pruebas automáticas de fragmentos de código, la inclusión docstrings de módulos de Python (docs API), y más.

A simple vista es genial esta herramienta, vamos a tener que probarla.

Dejo link: http://sphinxsearch.com/