Lenguajes de marcas ligeras

¿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

• Chuleta ReST
• 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
• Manual de rst2pdf (y rst en general): http://rst2pdf.ralsina.com.ar/ y http://lateral.netmanagers.com.ar/static/manual.pdf
• Presentación rst http://catherinedevlin.pythoneers.com/presentations/rst/olf.html
• Tutorial en francés: http://culot.org/public/Docs/documentation_rest.html

• rst2pdf Handbook

¿Cómo escribo rst?

Documento de texto

Escribe un documento de texto plano. 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
+++++++++++++++++++++++++

Estilo de texto

*cursiva* o **negrita**. ``texto en espacio fijo.``

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.

Más ejemplos con rst

Ejemplo: http://catherinedevlin.pythoneers.com/presentations/rst/show.rst

Resultado: http://catherinedevlin.pythoneers.com/presentations/rst/show.html

Herramientas de conversión

• Online: http://www.tele3.cz/jbar/rest/rest.html
• Instalo docutils y rst2pdf. Instalación de doctuils y rst2pdf
• Pandoc http://johnmacfarlane.net/pandoc/

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
user@home $ rst2html --stylesheet=miHojadeEstilos.css doc.rst  # ruta de la hoja de estilos

Pandoc

http://johnmacfarlane.net/pandoc/demos.html

• HTML fragment:

   pandoc README -o example1.html

• HTML en un fichero

   pandoc -s README -o example2.html

• HTML con tabla de contenidos, CSS y pie

  pandoc -s -S --toc -c pandoc.css -A footer.html README -o example3.html

• LaTeX:

   pandoc -s README -o example4.tex

• reStructuredText:

   pandoc -s -w rst --toc README -o example6.text

• Rich text format (RTF):

   pandoc -s README -o example7.rtf

• Beamer slide show:

 pandoc -t beamer SLIDES -o example8.pdf

• Convertir página web

   pandoc -s -r html http://www.gnu.org/software/make/ -o example12.text

• OpenDocument XML:

   pandoc README -s -w opendocument -o example20.xml

• ODT (OpenDocument Text, readable by OpenOffice):

   pandoc README -o example21.odt

• MediaWiki

 pandoc -s -S -w mediawiki --toc README -o example22.wiki

• EPUB ebook:

   pandoc -S README -o README.epub

• Word docx:

   pandoc -s -S README -o example29.docx

Mejorando la presentación

• Crear estilos personalizados: http://docutils.sourceforge.net/docs/user/slide-shows.html
• Ejemplos de css para probar:
  • http://docutils.sourceforge.net/docs/howto/html-stylesheets.html
  • http://docutils.sourceforge.net/sandbox/stylesheets/
  • http://trac.edgewall.org/browser/trunk/doc/utils/tracsphinx.css
  • http://culot.org/public/Docs/docutils.css
  • http://rst2a.com/gallery/html/
• Temas para S5: http://meyerweb.com/eric/tools/s5/themes/

En Windows

• Instalo Python (http://www.python.org/download)
• Instalo setuptools
  • Descargar y ejecutar el archivo peak.telecommunity.com/dist/ez_setup.py desde el intérprete de comandos (cmd)

C:\Python27\python.exe ez_setup.py

• Instalo docutils
  • Descargar y descomprimir http://docutils.sourceforge.net/docutils-snapshot.tgz
  • Ejecutar el archivo setup.py dentro de la carpeta descomprimida o

C:\Python27\python.exe setup.py install

• Descargar e instalar Reportlab:
  • Para 32 bits: http://www.reportlab.com/ftp/reportlab-2.5.win32-py2.7.exe o
  • Para 64 bits: http://www.reportlab.com/ftp/reportlab-2.5.win-amd64-py2.7.exe
• Descargar e instalar la última versión del repositorio http://code.google.com/p/rst2pdf/source/checkout. Hace falta un cliente de subversion (como http://tortoisesvn.tigris.org/ ). En el servidor del aula dejamos una copia.

C:\Python27\python.exe setup.py install

Ya está todo instalado! Uso:

C:\Python27\Scripts\rst2html  origen.rst destino.html
C:\Python27\Scripts\rst2pdf.exe origen.rst [-s estilo.txt] -o destino.pdf

Creación de presentaciones con rst2pdf

Tip: rst2pdf tiene problemas con doctuils 0.8 . Es mejor instalar la versión del repositorio:

$ svn checkout http://svn.berlios.de/svnroot/repos/docutils/trunk/docutils
$ cd docutils
$ sudo python setup.py install

• Presentaciones: http://lateral.netmanagers.com.ar/tr/es/stories/BBS52.html
• Otro ejemplo con http://fausto23.wordpress.com/2010/10/15/otro-modo-de-hacer-presentaciones/
• Modificación de estilos: http://python.org.ar/pyar/Recetario/EstilosRst2Pdf
• Unos ejemplos para practicar: https://subversion.american.edu/aisaac/misc/
• Comandos de creación

$ rst2pdf -s estilo.txt  slides.rst  -b1 -o slides.pdf 
$ rst2pdf -s estilo.txt  slides.rst  -e inkscape -b1 -o slides.pdf  # para poder usar svg

Actividad

Descarga la plantilla de http://lateral.netmanagers.com.ar/static/rst2pdf-slides/slides.style Utilízala con el comando anterior Modifícala Comprueba los cambios

Ejemplos para practicar y aprender

En muchos proyectos se usa restructuredtext para documentar y generar distintos formatos de doc. Mira estos ejemplos interesantes:

• Pycon Argentina: Machete de python Repositorio: https://github.com/ralsina/python-cheatsheet/
• Chuleta de expresiones regulares en rst : blog y github