Última actualización el 11 de abril de 2020
Miguel Menéndez nos dio una charla muy instructiva e interesante, sobre este creador de documentación, que reúne las mejores características, y entre las mas destacadas, la productividad y eficacia
Sphinx es una herramienta que facilita la creación de documentación inteligente y estética, escrita por Georg Brandl y licenciada bajo la licencia BSD.
Fue creado originalmente para la documentación de Python , y tiene excelentes prestaciones para la documentación de proyectos de software en una gran variedad de idiomas.
Entre otras, Sphinx tiene estas principales características:
* Formatos de salida: HTML (incluida la Ayuda HTML de Windows), LaTeX (para versiones PDF imprimibles), ePub, Texinfo, páginas de manual, texto sin formato
* Amplias referencias cruzadas: marcado semántico y enlaces automáticos para funciones, clases, citas, términos del glosario y piezas de información similares.
* Estructura jerárquica: definición fácil de un árbol de documentos, con enlaces automáticos a hermanos, padres e hijos.
* Índices automáticos: índices generales así como índices de módulos específicos del idioma
* Manejo de código: resaltado automático usando el resaltador Pygments
* Extensiones: pruebas automáticas de fragmentos de código, inclusión de cadenas de documentos de módulos de Python (documentos de API) y más
* Extensiones contribuidas: más de 50 extensiones contribuidas por usuarios en un segundo repositorio; la mayoría de ellos instalables desde PyPI
Miguel nos mostró las características de otros compositores, equivalentes a Sphynx:
* Latex que tiene como ventajas, que está mas enfocado a impresión y ambito profesional. Su principal inconveniente es que tiene una sintaxis mas compleja. Nos mostró ejemplos de codigo con todo lujo de detalles.
* Markdown su principal ventaja es que está mas enfocado a web. Es muy rápido formatear un documento con el. Su inconveniente, es que a veces necesita extensiones para algunos formatos concretos.
* Html, que está enfocado a navegadores Web
En los aspectos prácticos, Miguel nos enseñó como instalarlo en GNU/Linux, y nos mostró la estructura de un proyecto de presentación, de manera que quedó clarísmo como trabaja este Software usando RST y MArkdown
Sphinx está escrito en Python, que pasa por ser uno de los mejores lenguajes de programación.
Nos permite la utilización de plantillas y cuenta con un control de versiones, excelente.
Miguel nos mostró algunos comandos que son básicos paera la generación de contenido, y también el resultado de la compilación a diferentes lenguajes.
La traducción entre formatos también es una potente característica de Sphinx, que permite dar salida a un poyecto, sea cual sea nuestra preferencia final.
Una magnífica tarde, con una buena asistencia, que demostró bien a las claras, que Sphinx es apreciado por la comunidad y que levanta expectación, en cuanto alguien con el conocimineto técnico de Miguel, propone una charla.
Nuevos amigos asistieron, atraídos por tan interesante tema, y quedaron tan contentos, que repetirán la experiencia con otro de nuestros «Hablemos».
Si queréis consultar las diapositivas que se utilizaron en la charla, solo tenéis que pinchar en este enlace