Usuario:Lmorillas/modulo lenguajes de marcas/ligeros/rst

¿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


 * 1) . Lista numerada
 * 2) . 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 &lt;origen.rst&gt; &lt;destino.html&gt; --&gt; crea destino.html $ rst2pdf &lt;origen.rst&gt; --&gt; crea origen.pdf

Ejemplos:

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

pandoc -s -S README -o example29.docx
 * Word 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
C:\Python27\python.exe ez_setup.py C:\Python27\python.exe setup.py install C:\Python27\python.exe setup.py install
 * 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)
 * Instalo docutils
 * Descargar y descomprimir http://docutils.sourceforge.net/docutils-snapshot.tgz
 * Ejecutar el archivo setup.py dentro de la carpeta descomprimida o
 * 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.

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

 * 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

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