Diferencia entre revisiones de «Usuario:Lmorillas/modulo lenguajes de marcas/ligeros/rst»
De WikiEducator
(→Documentación de referencia) |
|||
| Línea 13: | Línea 13: | ||
=== Documentación de referencia === | === Documentación de referencia === | ||
| + | * [[http://ubuntuone.com/1M7C5fdbLkggF7ptoUvTq8 Chuleta ReST]] | ||
*http://sphinx.pocoo.org/rest.html | *http://sphinx.pocoo.org/rest.html | ||
*http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html | *http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html | ||
| Línea 19: | Línea 20: | ||
* Presentación rst http://catherinedevlin.pythoneers.com/presentations/rst/olf.html | * Presentación rst http://catherinedevlin.pythoneers.com/presentations/rst/olf.html | ||
*Tutorial en francés: http://culot.org/public/Docs/documentation_rest.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? === | === ¿Cómo escribo rst? === | ||
Revisión de 00:59 4 oct 2012
Contenido
¿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://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
¿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]
Ejemplos de uso
Abro un terminal. Ejemplo en linux:
$ rst2html <origen.rst> <destino.html> --> crea destino.html $ rst2pdf <origen.rst> --> crea origen.pdfEjemplos:
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
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
|
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
