Saltar al contenido

«Hablemos» de Febrero. Como generar documentación, de manera productiva y eficaz, con Sphinx

Ú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

Utilizamos cookies propias solo para los inicios de sesión del sitio. Si está de acuerdo clique Aceptar, si no lo hace, y necesita usar esta funcionalidad, no le aseguramos un perfecto funcionamiento de la misma. Más información en nuestra    Política de Cookies
Privacidad