1.5. Documentación con reStructuredText (reST)¶
Contents
1.5.1. Conceptos básicos¶
Introducción¶
La sintaxis de marcado de reStructuredText es un sencillo lenguaje de marcado fácil de leer en texto plano, con un procesador que lo convierte en un documento. Es útil para documentar programas con textos incrustados en el código (como docstrings de Python), para crear páginas web sencillas, o para generar documentos para imprimir.
Nota
El código para Sphinx se escribe en reST. Sin embargo, sphinx añade directivas adicionales sobre la sintaxis de reST. Por tanto, el código sphinx puede no ser totalmente compatible con reST.
El lenguaje usado por docutils es semejante a LaTeX, pero mucho mas fácil de leer en texto plano. Se procesa para generar una página web, o un documento PDF.
Párrafos¶
Se considera un párrafo cualquier bloque de texto que esté separado de otros por líneas en blanco
Advertencia
como en Python, la sintaxis de reST es sensible a la indentación!
Advertencia
reST requiere líneas en blanco entre los párrafos.
Directivas¶
Para marcar bloques, reST se basa en directivas que se definen así:
.. <name>:: <arguments>
:<option>: <option values>
contenido
Advertencia
La directiva debe tener un espacio separandola del argumento, y la opcion tambíen denbe tener un espacio separándolo del valor. El contenido debe tener una línea en blanco encima y otra debajo.
Ejemplo:
.. image:: ../images/test.png
:width: 200pt
Ciertos plugins proporcionan directivas extendidas(p.e., toctree de sphinx).
Comentarios¶
Se pueden incluir comentarios que no saldrán en el documento, poniendo dos puntos así:
.. Esto es un comentario
Esquema¶
Títulos¶
Para escribir un título, simplemente subrayelo:
******
Título
******
subtítulo
#########
subsubtítulo
************
y sigue así
Se deben poner al menos tantos caracteres como la longitud del título. La elección de caracteres es flexible, pero sea consistente. No hay una regla que determine que caracter se usa en cada nivel, ya que la estructura se determina por la sucesión de títulos. Sin embargo, para la documentación de Python sí se usa una convención que no cuesta seguir:
- # arriba y abajo, para partes
- * arriba y abajo, para capítulos
- =, para secciones
- -, para subsecciones
- ^, para subsubsecciones
- “, para párrafos
Sustituciones¶
Una forma es añadir al final del documento algo como:
.. _Python: http://www.python.org/
Entonces, cada vez que se encuentre la palabra Python_, es resultado será: Python .
La otra forma es así:
.. |habitual| replace:: esta es una frase que se repite o que va en una tabla
Y ahora se puede poner |habitual| y será sustituido por la frase.
Nota
Cuando define una referencia o un alias, el subrayado va antes de la parabra. Cuando hace referencia a él, el subrayado o barra bajo va despues. El subrayado posterior también se usa para referencias internas, citas, sustituciones ...
Nota
- Los bloques de sustitución pueden contener directivas::
Y así cada vez que se encuentre el alias |logo|, resultará en una imagen 
.
Nota
Puede ser necesario crear un alias para textos largos que deben ir en una celda de una tabla:
+---------+---------+-----------+
| |logo| | |logo| | |longtext||
+---------+---------+-----------+
|
|
este es un texto muy largo que no podría caber dentro de una celda de una tabla. |
Caracteres de marcado¶
Ciertos caracteres especiales se interpretan si coinciden con un patrón establecido, como los de la tabla siguiente.
Tenga en cuenta las limitaciones de este marcado:
- No puede ser anidado.
- El contenido no puede comenzar o terminar con un espacio: * texto* no es correcto,
- Debe ser separado del texto adyacente con carácteres que no sean texto (espacio, salto). Si desea poner reStructuredText, debe escribirlo así: re\ *Structured*\ Text
| Texto | Resultado | Notas |
|---|---|---|
| *cursiva* | cursiva | x |
| **negrita** | negrita | x |
| `texto interpretado` | (ver nota) | La salida y significado del texto interpretado depende de la aplicación. Puede usarse para cosas como entradas de índice o marcado descriptivo explícito (como identificadores del programa) |
| ``texto literal`` | texto literal | Normalmente sale como texto de anchura fija. Los espacios se conservan, pero los saltos de línea no. |
| enlace_ | enlace_ | Un enlace sencillo de una sola palabra. |
| `frase de enlace`_ | enlace_ | Un enlace sencillo con espacios o puntuación tiene que meterse entre comillas invertidas. |
| anonimo__ | anonimo__ | Con dos subrayados en lugar de uno, el enlace puede ser anonónimo (el texto de referencia no se repite en el objetivo). |
| _`objetivo interno` | objetivo interno | Un objetivo al que apuntan enlaces. |
| |sustitución| | (ver nota) | El resultado se procesa desde una definicion de sustitución. Puede ser un texto, una imagen, un enlace, o una combinación de todos. |
| nota al pie [1]_ | nota al pie [1]_ | Ver |
| cita [CIT2002]_ | cita [CIT2002] | Ver |
| http://docutils.sf.net/ | http://docutils.sf.net/ | Un hipervínculo normal. |
1.5.2. Formato¶
Formato de texto¶
El marcado permite que palabras o frases tengan determinado estilo (como cursiva o negrita) o funcionalidad (como enlaces).
Enfasis¶
- Use un asterisco a cada lado del texto que quiere enfatizar en itálica y 2 asteriscos si desea que sea negrita.
- Se usan dos comillas invertidas para hacer un texto literal. Por ejemplo, si desea usar carácteres especiales como *.
- Una sola comilla invertida se usa para comandos especiales de reST (p.e., hipervínculos con espacios).
Caracteres especiales¶
Asterisco, comilla invertida, barra vertical y subrayado (o barra baja) son carácteres delimitadores. Asterisco, comilla invertida y la barra vertical actúan como unas comillas: rodean la palabra o frase marcada, espacios en blanco u otras marcaciones no pueden estar dentro. Si desea usar un carácter delimitador literalmente, escápelo (con barra invertida “\\”) o márquelo (con dobles comillas invertidas); es decir que use literales.
En detalle, la especificación de reStructuredText dice que en el marcado en línea, se aplican las siguientes reglas a las cadenas de inicio y final (delimitadores de marcado):
- La cadena de inicio debe empezar un bloque de texto o estar inmediatamente precedido poy un espacio o ‘ ” ( [ { o <.
- La cadena de inicio debe ser inmediatamente seguida por un carácter que no sea el espacio.
- La cadena de final debe estar precedida por un carácter que no sea el espacio.
- La cadena de final debe poner fin a un bloque de texto (final de documento o seguido por una línea en blanco) o estar inmediatamente seguida de un espacio ó cualquier carácter ‘ ” . , : ; ! ? - ) ] } / ó >.
- Si una cadena de inicio está inmediatamente precedida por un ‘ ” ( [ { ó <, no debe ser inmediatamente seguida con el carácter correspondiente ‘ ” ) ] } ó >.
- Una cadena de final debe estar separada de una cadena de inicio por al menos un espacio.
- Una barra invertida sin escapar precediendo una marca de inicio o de final, desactivará el reconocimiento de marcado, excepto para la marca de final de los literales.
Nota
Si el texto contiene asteriscos o comillas invertidas que puedan ser confundidos por el procesador con delimitadores de marcado, tendrán que ser escapados con una barra invertida (“\”).
Advertencia
En docstrings de Python es necesario escapar las barras invertidas para que lleguen a ser vistas por reStructuredText. La forma más sencilla es usar cadenas raw (en bruto):
| Python string | Resultado |
|---|---|
| r"""\*escape* \`with` "\\"""" | *escape* `with` "\" |
| """\\*escape* \\`with` "\\\\"""" | *escape* `with` "\" |
| """\*escape* \`with` "\\"""" | escape with "" |
Referencias¶
La barra baja se usa para crear enlaces.
Referencias internas¶
Todos los títulos son considerados objetivos para enlaces internos que pueden ser enlazados usando la siguiente sintaxis:
`Enlaces internos y externos`_
Puede crear un destino para hipervínculos:
.. _inicio:
Y entonces inserte inicio_ en el texto para crear un enlace. Por ejemplo, saltar al inicio_ de este documento.
Enlaces al exterior¶
Para crear un enlace externo, use:
`Python <http://www.python.org/>`_
Y se creará un hipervínculo como Python.
Nota
Si necesita un subrayado dentro del nombre o el enlace, debe escaparlo con ‘\’.
Notas al pie¶
Para notas al pie, use [#name]_ para marcar el enlace, y agrege el objetivo al final del documento, después de una directiva rubric, así:
Este texto requiere una nota [#f1]_ .
.. rubric:: Notas al pie
.. [#f1] Texto de la nota.
También puede especificar el número ([1]_) o usar la numeración automática ([#]_). Aqui hay un ejemplo [1].
Listas¶
El siguiente código:
* Esta es una lista sin numerar.
* Tiene dos elementos, y este ocupa
dos líneas (observe la indentación)
1. Esta es una lísta numerada.
2. Y tiene dos elementos.
#. Esta es una lista con numeración automática.
#. Y tiene dos elementos, también.
Produce:
- Esta es una lista sin numerar.
- Tiene dos elementos, y este ocupa dos líneas (observe la indentación)
- Esta es una lísta numerada.
- Y tiene dos elementos.
- Esta es una lista con numeración automática.
- Y tiene dos elementos, también.
Nota
Si dos listas sólo estan separadas por una línea en blanco, entonces no se diferencian, como ha visto en el ejemplo.
Tablas¶
Hay varias formas de definir una tabla.
| simple: | Las tablas sencillas se pueden escribir así: +---------+---------+-----------+
| 1 | 2 | 3 |
+---------+---------+-----------+
Resultado:
|
|||||||||||||
|---|---|---|---|---|---|---|---|---|---|---|---|---|---|---|
| compleja: | Si hay celdas combinadas: +------------+------------+-----------+
| Header 1 | Header 2 | Header 3 |
+============+============+===========+
| body row 1 | column 2 | column 3 |
+------------+------------+-----------+
| body row 2 | Cells may span columns.|
+------------+------------+-----------+
| body row 3 | Cells may | - Cells |
+------------+ span rows. | - contain |
| body row 4 | | - blocks. |
+------------+------------+-----------+
Resultado:
|
|||||||||||||
| resumida: | Se puede resumir así: ===== ===== ======
Inputs Output
------------ ------
A B A or B
===== ===== ======
False False False
True False True
===== ===== ======
Resultado:
|
|||||||||||||
| listado: | Se pueden escribir las tablas con una directiva en forma de lista, lo que permite celdas con más texto: .. list-table:: TABLA
:widths: 50 50
:header-rows: 1
* - Opcion
- Valor
* - x
- 1
Resultado:
|
|||||||||||||
Recuadros¶
Notas¶
Hay directivas como que crean bonitas cajas de color:
Ver también
Esta es una caja seealso para “Véase también”::
creada usando:
.. seealso:: Vea también que se pueden anidar otras directivas, pero no todas.
Nota
También puede usar note para crear una nota.
Advertencia
Use warning para crear una advertencia.
Tópicos¶
Una directiva topic permite crear una caja con título personalizado:
.. topic:: Título personalizado
El cuerpo de la caja es un párrafo indentado.
Resulta:
Título personalizado
El cuerpo de la caja es un párrafo indentado.
Barra lateral¶
Se puede crear una barra lateral
usando el siguiente código:
.. sidebar:: Título de la barra
:subtitle: Subtítulo opcional
Este párrafo indentado es el contenido
de la barra, y se interpreta como
elemento de body.
Nota
Las barras salen como cajas flotantes, pueden no quedar bonitas.
Directivas especiales¶
| Etiquetado: |
:Etiqueta: Esto sirve para crear fichas tipo formulario
|
||
|---|---|---|---|
| glosario: | .. glossary::
Diccionario
matriz asociativa.
Resulta:
|
||
| centered: | .. centered::
|
||
| index: | .. index::
|
Ilustraciones¶
Imagen¶
Use:
.. image:: ../images/wiki_logo_openalea.png
to put an image
Nota
As mentionned earlier, a directive may have options put between two columns:
.. image:: ../images/wiki_logo_openalea.png
:width: 200px
:align: center
:height: 100px
:alt: alternate text
Figura¶
.. figure:: ../images/wiki_logo_openalea.png
:width: 200px
:align: center
:height: 100px
:alt: alternate text
:figclass: align-center
figure are like images but with a caption
and whatever else youwish to add
.. code-block:: python
import image
gives
figure are like images but with a caption
and whatever else youwish to add
import image
1.5.3. Documentar código¶
Código y literales¶
| sencillo: | Los Bloques literales de código fuente deben estar indentados, y se marcan finalizando el párrafo anterior con dos dos puntos: Por ejemplo::
import sphinx
print 'import done'
y: Por ejemplo:
::
import sphinx
print 'import done'
resultan: Por ejemplo: import sphinx
print 'import done'
|
||
|---|---|---|---|
| código fuente: | Por omisión la sintaxis es la de Python, pero se puede especificar el lenguaje: .. code-block:: html
:linenos:
<h1>Título1</h1>
produces
|
||
| archivo: | Se puede incrustar el contenido de otro archivo así: .. literalinclude:: filename
:linenos:
:language: python
:lines: 1, 3-5
:start-after: 3
:end-before: 5
|
Tabla de Contenidos¶
Como reST no permite interconectar varios documentos, o dividirlos en partes, Sphinx usa una directiva especial para declarar relaciones entre los archivos que forman la documentación, así como tablas de contenidos. La directiva toctree es la clave.
.. toctree::
:maxdepth: 2
intro
chapter1
chapter2
Se puede usar la opción glob para poder hacer:
.. toctree::
:glob:
intro*
recipe/*
*
El nombre del archivo es lo que se usa para poner la entrada en el índice. Puede especificar su propio texto de la siguiente forma:
.. toctree::
:glob:
intro
Capítulo1 descripción <chapter1>
Autodocumentacíon de código python¶
Supongamos que tiene un archivo python llamado test.py con una función llamada myfunction
.. module:: test
:platform: Unix, Windows
:synopsis: ejemplo de documentación automática
.. autofunction:: myfunction
Use la directiva module crea un índice (vea la parte superior derecha de esta página)
Advertencia
el código python debe estar en PYTHONPATH.
Ver también
Agregar tests con doctests¶
Se pueden incluir tests directamante en los documentos reSt, que no se verán en la documentación final:
.. doctest::
>>> import math
>>> print math.sqrt(2.)
1.41421356237
Y ejecutando un make doctest se ejecutaran todas las líneas que comiencen por >>>` comprobando que devuelven lo se especifica.
Nota
Se puede evitar comprobar el resultado añadiendo un comentario #doctest: +SKIP al final de una línea. Tambien se puede desactivar completamente con la opción ``:options: +SKIP
Ver también
1.5.4. Avanzado¶
Contenidos
- 1.5. Documentación con reStructuredText (reST)