Manual_Restructured_Text_Latex_Sphinx_Ed_1.0

Manual_Restructured_Text_Latex_Sphinx_Ed_1.0

Manual de
Usuario
RestructuredText, Latex y
Sphinx
Ed. 1.0.0
Enero 20, 2011
Ingenio Sólido S.A.S
Nit: 900363185-6
Jaime Andrés García Mejía
Contenido
1 Introducción
1
2 Estructura de un Manual de Usuario Básico
2
3 Comparación de Tecnología para hacer manuales de usuario
3
3.1 Restructured Text vs Latex
4
3.1.1 Formato Básico
4
3.2 Títulos
4
3.3 Listas
4
3.4 Listas numeradas
4
3.5 Imágenes
5
3.6 Tabla sencilla
5
4 Latex
7
4.1 Instalación de Latex
7
4.2 Construcción de Formato
7
4.3 Distribucción de las márgenes en Latex
8
5 Sphinx
10
5.1 Python
10
5.2 Sphinx
10
5.3 Rst2Pdf
10
5.4 PIL
10
5.5 Instalación del Software en Windows
10
5.6 Utilización de Sphinx
11
5.7 Manual de referencia de Text
12
5.7.1 Títulos y subtítulos
12
5.7.2 Saltos de página
12
5.7.3 Listas
12
5.7.4 Imágenes
13
Sección 1 Introducción
1
1 Introducción
Ingenio Sólido como empresa desarrolladora de hardware y software esta
constantemente elaborando documentación técnica y manuales de usuario para sus
productos. Para nosotros la documentación se relaciona directamente con los procesos
de desarrollo, estandarización y soporte. Una buena documentación agiliza el proceso de
adaptación de tecnologías empleadas en otros proyectos y el desarrollo de nuevas
tecnologías, permite la estandarización de los procesos de diseño electrónico y
programación y disminuye la demanda de soporte básico por parte de los clientes.
Teniendo en cuenta la gran cantidad de documentación a elaborar, procesadores de
texto como Open Office Writer, Google Docs o Microsoft Word no proveen la rapidez de
construcción ni los resultados que nuestros estándares de calidad exigen. Por esta razón
Ingenio Sólido ha optado por utilizar otras herramientas de elaboración de
documentación que en principio pueden parecer más complejas de utilizar pero que a
largo plazo disminuye el proceso a menos de la mitad y que ofrece unos resultados
realmente sorprendentes.
En esta serie de artículos, se establecerá una estructura guía para manuales de usuario y
se explicará el proceso de instalación y uso de los lenguajes para construcción de
documentación RestructuredTex y Latex.
En la primera parte se revisará el proceso de estructuración de un manual de usuario, y
se mostrarán algunos ejemplos de documentación.
Manual de Usuario
Sección 2 Estructura de un Manual de Usuario
Básico
2
2 Estructura de un Manual de Usuario
Básico
A continuación se describe la estructura mínima recomendada para un manual de usuario
básico. En los casos de manuales de usuario extensos o complejos, sería bueno
considerar una sección para el glosario y un índice.
• Portada: En esta página esta el título del manual, una imagen del producto, el logo
de la empresa y el número de versión del documento.
• Título: En esta página se muestra información sobre el producto al que pertenece el
manual y la empresa que lo elaboró, derechos de autor yacuerdos de licencia de
uso.
• Histórico de revisiones: En esta sección se muestra un tabla explicando los cambios
que ha tenido el manual en cada versión que se ha realizado.
• Tabla de contenido: Lista el contenido del manual. En caso de manuales extensos,
se deberían incluir también lista de tablas y lista de figuras.
• Contenido del Manual
• Encabezado y Pie de Página: Deberían mostrar el número de la página y la
sección. Esto permitirá al usuario guiarse dentro del documento.
• Prefacio: En esta sección se debe realizar la descripción general del
producto, requerimientos para usarlo y descripción de los capítulos que
componen el manual.
• Guía Rápida de uso: En los casos donde el producto tiene muchas
funciones, puede ser bueno incluir una guía rápida de como utilizarlo. Esta
guía debe buscar ser corta y útil para la mayor cantidad de personas
dentro del público objetivo.
• Manual de Usuario: Se refiere al contenido principal, para la construcción
del contenido es importante tener que su profundidad depende del público
al que va dirigido. Por lo tanto a pesar de que usted considere que hay
pasos obvios, estos no necesariamente lo son para su cliente. En los
casos de que el manual busque ser referencia de desarrollo, es apropiada
la incluición de diseños electrónicos y segmentos de código.
• Solución de problemas comunes – Preguntas frecuentes: En esta sección
se registra las preguntas y problemas más comunes respecto al producto.
Es importante ir actualizando esta sección a medida que se van
encontrando nuevos problemas en el uso del producto.
En cuanto a referencias de manuales de productos de hardware bien estructuradas, se
pueden destacar:
• Los elaborados por Microchip, por ejemplo el del PIC16f505.
• Los elaborados por Atmel, por ejemplo el del ATZB-24-A2B0.
Hay muchas buenas referencia en cuanto a manuales de productos de software, pero
quisiéramos destacar algunos realizados utilizando el software Sphinx, aplicación base
de esta serie de artículos sobre elaboración de manuales:
• Manual de Python http://docs.python.org/
• Manual de Django http://docs.djangoproject.com/
Sección 3 Comparación de Tecnología para hacer
manuales de usuario
3
3 Comparación de Tecnología para
hacer manuales de usuario
A continuación revisaremos la tecnología empleada para hacer manuales de usuario. En
primer lugar revisaremos en que casos se debería utilizar cada una de las herramientas.
Debería usar RestructuredText si voy a:
• Generar documentación en varios formatos (Por ejemplo HTML y PDF). También es
posible convertir Latex a HTML e incluso PDF a HTML, pero su soporte no es tan
bueno como el que proporciona un framework como Sphinx.
• Manuales de Usuario.
• Cotizaciones.
• Artículos.
Debería usar Latex si voy a:
• Hacer un trabajo de grado o un libro largo.
• Hacer un documento o publicación científica matemático. También se puede hacer
a través de Rest utilizando un plugin que utiliza las librerías matemáticas de Latex.
• Presentaciones. Tal vez en un futuro reevalúe esto, pero hay que destacar el poder
de la clase beamer de Latex.
• Manuales de Usuario.
• Cotizaciones.
• Artículos.
Debería usar un Procesador de texto si voy a:
• Hacer una carta, un memorando o un documento corto en general. Esta la ventaja
de no tener que compilar, por lo que en un documento de una o dos hojas sin
formato podría ser más rápido utilizar un procesador de texto.
• Ojalá que para nada más.
Como se pudo apreciar, tanto RestructuredText como el Latex, se pueden usar para
generar cualquier tipo de documentación, lo que buscaremos resolver a continuación es
¿en dónde radica la diferencia?
RST vs Latex
La primera respuesta a esta pregunta es el tiempo, Latex lleva más tiempo de desarrollo
lo que se traduce en un herramienta más robusta y con una comunidad más grande. Es
mucho más difícil encontrar ayuda para implementar algún tipo de estilo o formato
complejo en RestructuredText que en el Latex. La segunda respuesta es la sintaxis, de la
cual se mostrará algunos ejemplos en la próxima tabla, ya que como se podrá apreciar la
sintaxis de Restructured Tex suele ser más corta que la de Latex y más fácil de entender
Sección 3.1 Restructured Text vs Latex
y recordar.
3.1 Restructured Text vs Latex
3.1.1 Formato Básico
Restructured Text:
Negrilla **palabra*
Cursiva *palabra*
Latex:
Negrilla \textbf{ palabra }
Cursiva \textit{ palabra }
3.2 Títulos
Restrucuted Text:
Sección
=======
Subsección
---------Subsubsección
*************
Latex:
\section{Sección}
\subsection{Subsección}
\subsubsection{Sub-subsección}
3.3 Listas
Restructured Text:
- Primer ítem
- Segundo ítem
- Tercer ítem
Latex:
\begin{itemize}
\item Primer ítem
\item Segundo ítem
\item Tercer ítem
\end{itemize}
3.4 Listas numeradas
Restructured Text:
4
Sección 3.5 Imágenes
5
#. Primer ítem
#. Segundo ítem
#. Tercer ítem
Latex:
\begin{enumerate}
\item Primer ítem
\item Segundo ítem
\item Tercer ítem
\end{enumerate}
3.5 Imágenes
Restructured Text:
.. figure:: imagen.jpg
Latex:
\begin{figure}
\includegraphics{imagen.jpg}
\end{figure}
3.6 Tabla sencilla
1
2
3
4
5
6
Restructured Text:
.. list-table::
*-1
-2
-3
*-4
-5
-6
Latex:
\begin{table}
\begin{tabular}{ccl}
1 & 2 & 3 \\
4 & 5 & 6 \\
\end{tabular}
\end{table}
La parte más compleja en ambas sintaxis es el manejo de tablas, el uso de tablas
complejas (celdas de distinto tamaño entre filas), se maneja en RestructuredText hasta la
fecha utilizando ASCII-Art, algo como esto:
+------------+------------+-----------+
| Header 1 | Header 2 | Header 3 |
Sección 3.5 Imágenes
6
+============+============+===========+
| body row 1 | column 2 | column 3 |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
| body row 4 |
| - blocks. |
+------------+------------+-----------+
En Latex es necesario agregar algunas sentencias adicionales para indicar los
comportamientos distintos de las celdas, por ejemplo::
\begin{tabular}{|l|l|l|}
\hline
\multicolumn{3}{|c|}{Encabezado} \\
\hline
Campo & Campo & Campo \\ \hline
\multirow{4}{*}{Fila} & Campo & Campo \\
& Campo & Campo \\
& Campo & Campo \\
& Campo & Campo \\ \hline
\end{tabular}
Aún así hay herramientas para facilitar este proceso, por ejemplo en el caso del
RestructuredText está el Ascii Art Table, que permite generar tablas a partir de texto,
disponible aquí: http://sourceforge.net/projects/tableart/files/
Y para el caso de Latex, hay herramientas para generar las tablas a partir de una hoja de
cálculo de open office calc o desde Excel.
• Herramienta para generar tablas desde Calc.
• Herramienta para generar tablas desde Excel.
Para concluir se puede establecer que ambos lenguajes son adecuados para la
elaboración de documentación, el texto restructurado se caracteriza por tener una
sintaxis más fácil y el Latex por su robustez y que la parte más complicada del proceso
es la generación de tablas no simples, que puede ser facilitado a través de algunas
herramientas.
Sección 4 Latex
7
4 Latex
4.1 Instalación de Latex
En el caso de Linux, la mayoría de distribuciones ya tienen instalado Latex. En caso de
no ser así, en este sitio web http://www.tug.org/texlive/quickinstall.html encontrarán las
instrucciones pertinentes (no difíciles seguir para un usuario de Linux)
En el caso de Windows, se puede bajar la distribución de Latex Protext desde esta sitio
web http://www.tug.org/protext/, es un poco pesado (750 MB). La instalación es como la
de cualquier programa de Windows.
Para habilitar el idioma español en Latex (Silabeo y localización) , se debe seguir las
siguientes instrucciones:
Entrar a través de Inicio – Miktext 2.8 – Setting – Languages. Seleccionar spanish y con el
botón Up ponerlo como primero de la lista
Descargar el Diccionario en español http://wiki.services.openoffice.org/wiki/Dictionaries
Copiar diccionario en la carpeta dictionaries del programa Miktex
Latex
El lenguaje Latex puede ser escrito en cualquier editor de texto, aún así recomiendo
utilizar un IDE (Entorno Integrado de Desarrollo) para facilitar su construcción.
Recomiendo revisar los siguientes programas como opciones para edición de archivos
Latex:
• Texcnicenter (Windows) http://www.texniccenter.org/
• TexMaker (Mac, Windows, Linux) http://www.xm1math.net/texmaker/
• Gedit (Windows, Linux) http://www.xm1math.net/texmaker/
4.2 Construcción de Formato
Para la construcción del formato del documento, recomiendo generar un archivo de estilo
específico a parte del contenido. Para hacer esto basta con crear un archivo e incluirlo
con el siguiente comando: input{Styles} Donde el archivo Styles.tex contiene el estilo del
documento
Lo primero que debemos hacer es definir el tamaño de la hoja y las márgenes.
Sección 4.3 Distribucción de las márgenes en
Latex
8
En Latinoamérica se suele usar el tamaño carta, para decirle a latex que se debe usar
éste, basta con utilizar la etiqueta de tamaño de papel en la hoja de estilos:
setpapersize{USletter}
Además, para definir las márgenes del documento es recomendable utilizar el paquete
vmargin, para un mayor control sobre las mismas. Se debe tomar como referencia la
distribución de márgenes en Latex que se muestra en la siguiente imagen:
4.3 Distribucción de las márgenes en Latex
Márgenes de Latex
Sección 4.3 Distribucción de las márgenes en
Latex
9
Teniendo como referencia la imagen anterior, se utiliza la etiqueta setmargin como se
muestra a continuación::
\setmargins{hleftmargini}{htopmargini}{htextwidthi}
{htextheighti}{hheadheighti}{hheadsepi}{hfootheighti}{hfootskipi}
El siguiente paso es generar el estilo de la página en cuánto a su encabezado y pie de
página, en este caso incluiremos el número de página y una línea en el encabezado y un
pie de página vacío. Para hacer esto utilizamos el siguiente fragmento de código::
\defpagestyle{page}{
(\textwidth,0pt)
{\pagemark\hfill\headmark\hfill}
{\hfill\headmark\hfill\pagemark}
{\hfill\headmark\hfill\pagemark}
(\textwidth,1pt)}
{(\textwidth,0pt)
{\hfill}{\hfill}{\hfill}
(\textwidth,0pt)}
Ya que normalmente la portada del documento no tiene encabezado se debe especificar
en el contenido que la portada no utilizará ningún estilo. Para hacer esto se debe escribir
la siguiente etiqueta antes de escribir el contenido de la portada \pagestyle{empty}
Y luego agregar el estilo definido en la parte de arriba antes del resto del contenido (Para
que el contenido incluya el encabezado) \pagestyle{page}
Luego se debe definir el formato de la portada, que será utilizada en todos los
documentos que se generen. Un código ejemplo de la generación de una portada es el
siguiente::
\Large
\textsc{Manual de Usuariol}\\
\textsc{Nombre del Producto}\\
\vspace{4cm}
\textsc{Nombre de la Empresa}\\
\textsc{Nit de la Empresa}\\
\vspace{4cm}
\textsc{Nombre de la Empresa Cliente}\\
\textsc{\today}\\ %%Marca la fecha del día de hoy
\vspace{4cm}
\textsc{Nombre del Autor}\\
\textsc{Cargo del Autor}\\
\textsc{Celular del Autor}\\
\lowercase{Correo electrónico del autor}
Finalmente, explico el proceso para agregar un fondo en el documento, que he
encontrado que no esta muy bien especificado en la documentación de referencia.
Simplemente se debe utilizar la siguiente etiqueta::
\CenterWallPaper{1}{img/background.png}
Se recomienda utilizar un formato sin pérdida como el png, para tener un mejor resultado
en el pdf. Con esto concluimos, la exploración del lenguaje Latex, para más información
sobre la sintaxis del lenguaje recomiendo revisar el siguiente wikibook de referencia:
http://en.wikibooks.org/wiki/LaTeX
Sección 5 Sphinx
10
5 Sphinx
A continuaciónrevisaremos 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.
5.1 Python
Lenguaje de programación base para la utilización de los software Sphinx y Rst2Pdf
5.2 Sphinx
Es un generador de documentación que convierte texto reestructurado en HTML y otros
formatos como PDF.
Sphinx
5.3 Rst2Pdf
Es una herramienta escrita en Python y utilizado por Sphinx para la conversión de texto
restructurado a pdf.
5.4 PIL
Es una librería para el manejo de imágenes en Python.
5.5 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:Python27Scripts
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
Sección 5.6 Utilización de Sphinx
11
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.
5.6 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. Para
marcar los datos del autor se debe hacer separado por , como se muestra en el siguiente
ejemplo::
pdf_documents = [('index', u'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%"]
],
Sección 5.7 Manual de referencia de Text
12
background : "img/background.png",
}
5.7 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
5.7.1 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
+++++++++++++++++++++++++
5.7.2 Saltos de página
Cuando se necesita hacer un salto de página, se debe utilizar el siguiente código::
.. raw:: pdf
PageBreak
5.7.3 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
1. Lista numerada
2. Lista numeradas
Y el resultado es el siguiente:
• Lista con viñetas
Sección 5.7.4 Imágenes
13
• 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
5.7.4 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.