Última revisión de 06:48 22 ene 2014

¿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

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

$ 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