Docutils para escritura técnica
¿Qué sistema de documentación usar en un laboratorio de informática y robótica aplicada? Existen muchos sistemas de documentación para escritura técnica. En esta entrada se mencionan tres alternativas: Docutils, LaTeX y Publican. Además se da un ejemplo práctico de escritura y publicación de un documento con la primera de ellas.
Probando sistemas de documentación (otra vez) para usar en un laboratorio de tecnología informática y robótica aplicada. La idea es adoptar un sistema que sea funcional y lo suficientemente completo como para escribir documentos técnicos complejos. Con funcional me refiero a las definiciones dos y tres que da el DRAE sobre la palabra: algo que es fácil, útil, cómodo de emplear y adecuado para sus fines. Además, debe facilitar la exportación de documentos en formato HTML, que es el formato ideal para la Web, el mejor medio para compartir información con el mundo. Por último, debe tener una API que permita adaptar el sistema para necesidades específicas.
Mi lista de candidatos:
- Docutils
- Herramientas de documentación para propósitos generales y especiales. (Este es un sistema popular en la comunidad de Python).
- LaTeX
- Sistema para la producción de documentación técnica y científica de alta calidad tipográfica. Es el estándar de facto para la comunicación y publicación de documentos científicos.
- Publican
- Sistema de publicación de libros, artículos y colecciones. Adaptado particularmente, pero no exclusivamente, para publicación de libros y artículos técnicos sobre hardware y software.
Miremos un ejemplo de documento fuente de cada sistema. Los tres ejemplos producen un documento final con título, fecha, autor y tres párrafos. Aunque son ejemplos superficiales, se puede comparar la complejidad de cada lenguaje de marcas.
Empecemos con Docutils. Este sistema usa un lenguaje de marcas llamado reStructuredText.
========================== Mi primer artículo técnico ========================== :Autor: Augusta Ada King :Fecha: 2015-05-27 ¡Hola mundo! Este es mi primer documento escrito con reStructuredText. Eso es todo por ahora. Adiós.
Ahora un documento similar para el sistema LaTeX. Este sistema usa un lenguaje de marcas del mismo nombre, LaTeX.
\documentclass{article} \title{Mi primer artículo técnico} \author{Augusta Ada King} \date{Mayo 27 de 2015} \begin{document} \maketitle ¡Hola mundo! Este es mi primer documento escrito con LaTeX. Eso es todo por ahora. Adiós. \end{document}
Y finalmente la versión del documento para el sistema Publican. Este sistema usa el lenguaje de marcas DocBook.
<?xml version='1.0'?> <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.5//EN" "http://www.oasis-open.org/docbook/xml/4.5/docbookx.dtd"> <article xmlns='http://docbook.org/ns/docbook'> <info> <title>Mi primer artículo técnico</title> <author> <personname> <firstname>Augusta Ada</firstname><surname>King</surname> </personname> </author> <pubdate>2015-05-27</pubdate> </info> <para>¡Hola mundo! Este es mi primer documento escrito con DocBook.</para> <para>Eso es todo por ahora.</para> <para>Adiós.</para> </article>
Personalmente, el lenguaje de marcas de Docutils me parece más agradable a la vista; muy parecido a escribir prosa en un documento genérico de texto plano.
Después de ojear los documentos de referencia de los lenguajes de marcas usados por los tres sistemas y de ver documentos fuente y documentos finales creados con ellos, parece que todos cumplen con lo que se necesita en el laboratorio. Sin embargo, en esta entrada me centro en Docutils.
A continuación se muestra cómo instalar el sistema Docutils y se dan dos ejemplos prácticos de cómo escribir documentos y exportar sus versiones finales en HTML para publicarlos en la Web.
Instalación del sistema
Como el laboratorio se centra en investigar tecnología que contribuya a la libertad del ser humano, se descarta el uso de sistemas operativos como Microsoft Windows o Mac OS y se recomienda usar sistemas libres.
La mayoría de sistemas operativos libres ya vienen con Docutils instalado (por la importancia que tiene para Python). Pero, para comprobar, se puede ejecutar la siguiente orden en un terminal:
$ rst2html --version
rst2html es una de las herramientas de Docutils usada para convertir documentos reStructuredTex a HTML. Si Docutils está instalado, el resultado de la orden anterior es algo similar a esto:
rst2html (Docutils 0.12 [release], Python 2.7.9, on linux2)
En caso de error, tal vez Docutils no esté instalado o no todas sus herramientas estén instaladas. Use el sistema de administración de paquetes de sus sistema para verificar.
Documento sencillo y conversión a HTML
Figura 1. A la izquierda, un documento fuente escrito en reStructuredText en el editor gedit. A la derecha, el documento HTML resultante creado con rst2html y visto en un navegador Web.
Sigamos todo el proceso de escribir un documento sencillo y convertirlo a HTML.
Cree un documento nuevo y escriba el siguiente texto (reStructuredText):
=================== Mi primer documento =================== :Autor: Alan Brito :Fecha: Viernes 08 mayo 2015 .. image:: http://ur1.ca/kbpgv :alt: Vista panorámica desde el cerro Connors. Hoy aprendí a escribir mi primer documento en *reStructuredText*. Es fácil empezar a usarlo. A medida que vaya necesitando incluir cosas en el documento, consultaré el manual.
Guarde el documento como documento.rst.
Genere una versión HTML de documento.rst usando la herramienta rst2html de Docutils:
$ rst2html documento.rst documento.html
El documento HTML generado se puede ver en cualquier navegador Web y usa una apariencia predeterminada por Docutils que es suficiente en muchos casos. (Ver Figura 1).
Sin embargo, Docutils permite configurar varias propiedades para controlar la apariencia final del documento. Esto incluye especificar CSS personalizado. Se da un ejemplo de esto a continuación.
Documento con configuración personalizada
Figura 2. Documento reStructuredText convertido en HTML con propiedades personalizadas.
Docutils permite configurar varias opciones a la hora de generar el documento HTML final. La lista de opciones está disponible en la ayuda del programa:
$ rst2html --help
Es conveniente usar un archivo de configuración cuando se necesita cambiar frecuentemente varias propiedades del documento generado.
El ejemplo de la Figura 2 usa un archivo de configuración personalizado que, entre otras cosas, especifica el idioma del documento y hojas de estilo (CSS) que le dan una nueva apariencia.
Descargue el ejemplo para que explore los archivos. Para generar el documento HTML final, ejecute la siguiente orden dentro del directorio que contiene todos los archivos:
$ rst2html --config docutils.conf articulo.rst articulo.html
Conclusión
Docutils es un sistema suficiente para emplearlo en el laboratorio tanto para notas como para documentos técnicos más elaborados.
Aunque esta entrada solo se centra en escribir documentos tipo artículo y en su conversión a HTML, el sistema permite mucho más que eso. Si se quiere tener una mirada más amplia de las posibilidades del sistema, los siguientes temas pueden ayudar:
Exploración de las demás herramientas de conversión de Docutils:
rst2html rst2pseudoxml rstartd rst2latex rst2s5 rst-buildhtml rst2man rst2xetex rstpep2html rst2odt rst2xml rst2odt_prepstyles rstart
Escritura y publicación automática de manuales multipágina integrando Sphinx, sistemas de control de versiones y el servicio Read the Docs.
Uso de la API para Python de Docutils para escribir sistemas a la medida de administración y publicación de documentación.
Temas relacionados: