Blog Ingenio Sólido – Centro de Desarrollo Tecnológico

Terminando la serie de artículos sobre generación de documentación, revisaremos el proceso de instalación y utilización del software Sphinx. Para la elaboración de la documentación se utiliza el lenguaje RestructuredText y una serie de librerías de Python. A continuación se especifica el software que va a hacer utilizado.

Python

Lenguaje de programación base para la utilización de los software Sphinx y Rst2Pdf

Sphinx

Es un generador de documentación que convierte texto reestructurado en HTML y otros
formatos como PDF.

Rst2Pdf

Es una herramienta escrita en Python y utilizado por Sphinx para la conversión de texto
restructurado a pdf.

PIL

Es una librería para el manejo de imágenes en Python.

Instalación del Software en Windows

Para realización de la instalación del sistema en Windows, se deben seguir los siguientes pasos:

1. Instalar Python 2.7, el cual puede ser descargado en el sitio web oficial de Python

http://www.python.org.

2. Instalar Setup Tools para la versión de Python descargada, este puede ser
descargado en este sitio web http://pypi.python.org/pypi/setuptools

3. Agregar las siguientes variables en la variable de entorno PATH, para poder ejecutar
easy-install: C:\Python27;C:\Python27\Scripts

4. Abrir el Símbolo de Sistema y ejecuta los siguientes comandos:

easy_install -U Sphinx
easy_install rst2pdf
easy_install PIL

5. Para la escritura de la documentación se puede utilizar cualquier editor de texto, aún
así se recomienda la instalación de un IDE como Geany para un mejor manejo de las
tabulaciones. Se puede descargar una versión para Windows en el sitio oficial
http://www.geany.org/Download/Releases. Se recomienda además descargar los
plugins de Geany para tener funcionalidades como correción de ortografía. Además
sirve para programar otros lenguajes de programación como Java, HTML, C, etc.

6. Para generar el pdf del documento en Windows basta con ejecutar el archivo
makepdf.bat, dentro de la carpeta de código del documento. Esto generará
automáticamente el pdf del documento mostrando los errores en caso de generarse
alguno.

Utilización de Sphinx

Para generar un nuevo proyecto se puede utilizar el comando rápido $ sphinx-quickstart en una consola de windows en el lugar que se desea crear la carpeta con el documento. Esto generará todos los archivos necesarios para realización del documento.

Entre esos archivos se encuentra el conf.py. En este archivo se configura el nombre del proyecto, el nombre del archivo y otros datos de configuración. Para configurar las propiedades del pdf que se va a exportar, basta con modificar la línea pdf_documents, teniendo en cuenta la siguiente estructura

pdf_documents = [('index', u'nombre_del_archivo',
u'subtítulo del documento', u'datos del autor'),]

El nombre del archivo no debería contener espacios,tildes o caracteres extraños, como se muestra en el
siguiente ejemplo:

pdf_documents = [('index', u'Manuales_de_Usuario_con_ReestructuredText_Latex_Sphinx_Ed_1.0',
u'ReestructuredText, Latex y Sphinx',
u'Jaime Andrés García Mejía'),]

Adicionalmente en este archivo se establecen la lista de hojas de estilos que vamos a utilizar en la línea pdf_stylesheets = ['bg']

Por ejemplo esta línea esta indicando que se incluya el archivo bg.styles.

En este archivo se puede determinar tanto las márgenes del documento como el fondo que se utilizará, cambiando la información de PageSetup por las márgenes que se deseen. Recordar que margin-gutter es el espacio entre columnas.

{pageSetup: {
    width: "20cm",
    height: "5cm",
    margin-top: "5mm",
    margin-bottom: "3cm",
    margin-left: "3cm",
    margin-right: "3cm",
    margin-gutter: "1cm",
    spacing-header: "5mm",
    spacing-footer: "0mm"
}

Para poner el fondo simplemente se utliza la propiedad background, ejemplo:

    cutePage: {
        frames: [
            ["0", "0", "100%", "100%"]
        ],
        background : "img/background.png",
    }

Manual de referencia de Text

A continuación se explica lo básico para el uso del generador de documentación. Si se
necesita más información se pueden consultar los siguientes manuales de referencia.

• http://sphinx.pocoo.org/rest.html

• http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

Títulos y subtítulos

Para escribir un título basta con poner símbolos ‘=’ debajo del texto del título, de la
siguiente forma:

Título
====

Los símbolos = puestos debajo del texto deben tener el mismo tamaño que el título.

Para la escritura de subtítulos y subtítulos de segundo nivel, se utiliza los símbolos ‘-’ y
‘*’, respectivamente. Su utilización es igual que el de los títulos, ejemplo:

Subtítulo
---------

Subtítulo de Segundo Nivel
**************************

Subtítulo de Tercer Nivel
+++++++++++++++++++++++++

Saltos de página

Cuando se necesita hacer un salto de página, se debe utilizar el siguiente código:

.. raw:: pdf

PageBreak

Listas

Se pueden construir dos tipos de listas, numeradas o con viñetas. Para construir una lista
con viñetas basta utilizar el símbolo ‘*’, y para las numeradas el símbo ‘#.’. Ejemplo:

* Lista con viñetas
* Lista con viñetas

#. Lista numerada
#. Lista numeradas

Y el resultado es el siguiente:

• Lista con viñetas

• Lista con viñetas

1. Lista numerada

2. Lista numeradas

Tablas

Para construcción de tablas se debe definir el ancho de las columnas (este ajuste es
mediana automático, lo importante es restringir el tamaño de algunas columnas para que
la tabla quepa dentro de la hoja) y el número de filas que componen el encabezado. A
continuación se muestra un ejemplo:

.. list-table::
:widths: 50 15
:header-rows: 1

* - Título 1
- Título 2
* - Campo 1
- Campo 2
* - Campo 1
- Campo 2
* - Campo 1
- Campo 2

Imágenes

Para ingresar una imagen se utiliza el siguiente bloque de código:

.. figure:: img/nombre_archivo.png
    :width: 100%

    Descripción de la imagen

El campo width indica el tamaño de la imagen en el documento, un 100% indica que utiliza el máximo posible ya sea el tamaño de la imagen o el tamaño de la hoja.

En el siguiente enlace se muestra el resultado de la utilización de Sphinx para la generación de un manual en PDF. En este PDF se incluye toda la información explicada en esta serie de artículos.Manual_Restructured_Text_Latex_Sphinx_Ed_1.0

Con esto termina, la serie de artículos sobre Manuales de Usuario, no olvide hacer comentarios si tiene alguna duda o sugerencias. Además visite los sitios web de las aplicaciones y porque no, considere la realización de una donación a estas iniciativas para que continúen su proceso de desarrollo de mejores funcionalidades.

Índice de la Serie de Artículos:

Introducción
RestructuredText vs Latex
Introducción a Latex
Introducción a Sphinx

« Componentes de Joomla Google Apps en la empresa »