Diferencia entre revisiones de «Usuario:Lmorillas/modulo lenguajes de marcas/ligeros/rst»
De WikiEducator
(→Documentación de referencia) |
|||
(37 revisiones intermedias por el mismo usuario no mostrado) | |||
Línea 1: | Línea 1: | ||
− | {{MiTitulo | | + | {{MiTitulo | Lenguajes de marcas ligeras}} |
− | == ¿Qué es? == | + | === ¿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? === |
− | + | ||
− | + | ||
− | + | ||
− | == ¿Cómo escribo rst? == | + | *Escribo la documentación en texto plano y después la convierto a distintos formatos. |
− | ; Documento de texto | + | *Soporta versionado porque es texto |
− | : Escribe un documento de texto. Suelen tener extensión .rst o .txt | + | *Se puede leer con cualquier editor |
+ | |||
+ | === 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://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? === | ||
+ | |||
+ | ;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 | 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: | + | :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 | ||
--------- | --------- | ||
Línea 35: | Línea 47: | ||
+++++++++++++++++++++++++ | +++++++++++++++++++++++++ | ||
− | ; Estilo de texto | + | ;Estilo de texto |
− | : <nowiki>*cursiva* o **negrita**. ``texto en espacio fijo.`` | + | :<nowiki>*cursiva* o **negrita**. ``texto en espacio fijo.`` </nowiki> |
+ | |||
+ | ;Saltos de página en pdf | ||
+ | :Cuando se necesita hacer un salto de página, se debe utilizar el siguiente código: | ||
− | |||
− | |||
.. raw:: pdf | .. raw:: pdf | ||
− | + | PageBreak | |
+ | |||
+ | ;Listas | ||
+ | :listas con viñetas y numeradas: | ||
− | |||
− | |||
* Lista con viñetas | * Lista con viñetas | ||
* Lista con viñetas | * Lista con viñetas | ||
Línea 52: | Línea 66: | ||
#. Lista numeradas | #. Lista numeradas | ||
− | ; Imágenes | + | ;Imágenes |
+ | |||
.. figure:: img/nombre_archivo.png | .. 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. | + | :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 | + | === Herramientas de conversión === |
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | ||
− | + | *Online: http://www.tele3.cz/jbar/rest/rest.html | |
− | + | *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 === | ||
+ | |||
+ | Abro un terminal. '''Ejemplo en linux''': | ||
+ | |||
+ | $ rst2html <origen.rst> <destino.html> --> crea destino.html | ||
+ | $ rst2pdf <origen.rst> --> crea origen.pdf | ||
+ | |||
+ | Ejemplos: <source lang="bash"> | ||
+ | user@home $ rst2html intro.rst intro.html | ||
user@home $ rst2pdf intro.rst | user@home $ rst2pdf intro.rst | ||
+ | user@home $ rst2html --stylesheet=miHojadeEstilos.css doc.rst # ruta de la hoja de estilos | ||
</source> | </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 === | ||
+ | * 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 | ||
+ | <source lang="bash"> | ||
+ | $ 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 | ||
+ | </source> | ||
+ | {{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: | ||
+ | *[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 blog] y [https://github.com/tartley/python-regex-cheatsheet github] |
Última revisión de 06:48 22 ene 2014
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://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
¿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.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
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
|
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