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

Contenido

1 ¿Qué es?
2 ¿Qué puedo hacer?
3 Documentación de referencia
4 ¿Cómo escribo rst?
5 Herramientas de conversión
6 Ejemplos de uso
7 Pandoc
8 Mejorando la presentación
9 En Windows
10 Creación de presentaciones con rst2pdf
11 Actividad
- 11.1 Ejemplos para practicar y aprender

¿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:
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

@@ Línea 1: / Línea 1: @@
-{{MiTitulo | Restructured Text}}
+{{MiTitulo | Lenguajes de marcas ligeras}}
 === ¿Qué es?  ===
@@ Línea 13: / Línea 13: @@
 === Documentación de referencia  ===
+* [http://thomas-cokelaer.info/tutorials/sphinx/rest_syntax.html 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://lateral.netmanagers.com.ar/static/manual.pdf
+*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
+* [http://rst2pdf.ralsina.com.ar/handbook.html rst2pdf Handbook]
 === ¿Cómo escribo rst?  ===
@@ Línea 79: / Línea 82: @@
 *Online: http://www.tele3.cz/jbar/rest/rest.html
-*Instalo [[http://docutils.sourceforge.net '''doctuils''']] y [[http://code.google.com/p/rst2pdf/ '''rst2pdf''']]
+*Instalo [http://docutils.sourceforge.net '''docutils'''] y [http://code.google.com/p/rst2pdf/ '''rst2pdf''']. [[/instalacion_rst2pdf | Instalación de doctuils y rst2pdf]]
+* Pandoc http://johnmacfarlane.net/pandoc/
 === Ejemplos de uso  ===
@@ Línea 93: / Línea 97: @@
 user@home $ rst2html --stylesheet=miHojadeEstilos.css doc.rst  # ruta de la hoja de estilos
 </source>
+=== 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 ===
@@ Línea 103: / Línea 162: @@
 ** 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  ===
@@ Línea 126: / Línea 205: @@
 * Comprueba los cambios
 }}
-{{Actividad|
-'''Ejemplos explicados para practicar'''
+=== Ejemplos para practicar y aprender ===
 En muchos proyectos se usa restructuredtext para documentar y generar distintos formatos de doc.
 Mira estos ejemplos interesantes:
-* http://www.netmanagers.com.ar/index.php?page=machete-de-python
+*[http://www.netmanagers.com.ar/index.php?page=machete-de-python Pycon Argentina: Machete de python] Repositorio: https://github.com/ralsina/python-cheatsheet/
-* Chuleta de expresiones regulares en rst: http://tartley.com/?p=1349 y https://github.com/tartley/python-regex-cheatsheet
+*Chuleta de expresiones regulares en rst : [http://tartley.com/?p=1349 blog] y [https://github.com/tartley/python-regex-cheatsheet github]
-}}

Diferencia entre revisiones de «Usuario:Lmorillas/modulo lenguajes de marcas/ligeros/rst»

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

Contenido

¿Qué es?

¿Qué puedo hacer?

Documentación de referencia

¿Cómo escribo rst?

Herramientas de conversión

Ejemplos de uso

Pandoc

Mejorando la presentación

En Windows

Creación de presentaciones con rst2pdf

Actividad

Ejemplos para practicar y aprender

Menú de navegación

Herramientas personales

Espacios de nombres

Variantes

Vistas

Acciones

Buscar

Navegación

Herramientas

Imprimir/exportar