Sphinx – Generador de documentación Python

imagen / StuRap
  
20 de Febrero de 2015   0  

A la mayoría de los programadores se les hace un gran reto tener bien documentado el código que escriben, si bien no es una tarea del todo entretenida, sí que conlleva a enfrentar un gran reto que sea entendible por alguien que desea aprender de nuestro código.

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 maneja la licencia BSD.

Funciones destacadas:

  1. 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.
  2. 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.
  3. Estructura jerárquica: Definición sencilla de un árbol de documentos, con enlaces automáticos a padres e hijos
  4. Í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.
  5. Extensiones: Pruebas automáticas de fragmentos de código, la inclusión docstrings de módulos de Python (docs API), y más.

Sphinx utiliza reStructuredText como su lenguaje de marcas, y muchos de sus puntos fuertes provienen de la potencia y sencillez de reStructuredText, su análisis y la suite de traducción, y los Docutils.

¿Quiénes utilizan Sphinx?

Existe una gran lista de proyectos que han generado su documentación gracias a esta herramienta, solo por mencionar algunos puedo enlistar:

Así también existen libros completos que han sido escritos utilizando la herramienta Sphinx:

Cómo comenzar.

Podemos encontrar documentación de Sphinx en su página oficial, en la cual podemos aprender a dar nuestros primeros pasos con la herramienta. Así también podemos leer estaguía que nos muestra diferentes ejemplos de uso.



Alex Dzul

FullStack Python / Django Developer. #jslove

Etiquetas

Temas relacionados