Restructured Text

¿Qué es?

reStructuredText es un lenguaje de marcas ligero, de fácil lectura en su formato de fuente pero muy versátil para producir documentos complejos.

¿Qué puedo hacer?

• Escribo la documentación en texto plano y después la convierto a distintos formatos.
• Soporta versionado porque es texto
• Se puede leer con cualquier editor

Documentación de referencia

• http://sphinx.pocoo.org/rest.html
• http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html
• http://people.ee.ethz.ch/~creller/web/tricks/reST.html

¿Cómo escribo rst?

Documento de texto

Escribe un documento de texto. Suelen tener extensión .rst o .txt

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 en pdf

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

.. raw:: pdf

   PageBreak

Listas

listas con viñetas y numeradas:

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

#. Lista numerada
#. Lista numeradas

Imágenes

.. figure:: img/nombre_archivo.png
    :width: 100%
    :height: 100
    :scale: 50
    :alt: texto alternativo

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.

Herramientas de conversión

• Instalo [doctuils] y [rst2pdf]

Ejemplos de uso

Abro un terminal. Ejemplo en linux:

 $ rst2html <origen.rst> <destino.html>  --> crea destino.html
 $ rst2pdf <origen.rst> --> crea origen.pdf

Ejemplos:

user@home $ rst2html intro.rst intro.html
 
user@home $ rst2pdf intro.rst