ReStructured Text es un lenguaje de marcas ligero creado para escribir textos de manera cómoda y rápida. A la hora de crear un documento en formato ReStructuredText, disponemos de dos grandes bloques de marcas. Por un lado tenemos una serie de marcas orientadas al párrafo y al formatoe de este y su contenido, y por otro lado una serie de marcas o directivas que extienden las posibilidades de formato que nos ofrecen las primeras.

Vamos a ver estas dos marcas por separado, realizando un repaso breve por las más comúnmente usuadas dentro de la documentacion de gvsig.org.

La estructura más básica reconocida es el párrafo, que no es más que texto separado por líneas en blanco. Los párrafos deben tener la misma indentación o aparecerán sangrados.

Por ejemplo:

Esto es un párrafo. Es un poco corto.

    Este párrafo producirá como resultado un bloque indentado de texto, 
    usado típicamente para citar otro texto

Este es otro párrafo.

El resultado es:

Esto es un párrafo. Es un poco corto.

Este párrafo producirá como resultado un bloque indentado de texto, usado típicamente para citar otro texto

Este es otro párrafo.

Dentro de los párrafos y otros cuerpos de texto, puedes querer marcas de texto adicionales para itálica con "*italica*" o negrita con "**negrita**".

Si quieres que algo aparezca literalmente utiliza comillas dobles. Nota que no se interpreta el contenido de las comillas dobles así los asteríscos "*" etc. se quedan sólos

Si necesitas usar un carácter "especial" en el texto, generalmente estará bien, --reStructuredText es muy inteligente. Por ejemplo, este * asterísco está bien puesto. Si quieres que el /texto esté rodeado de asteríscos y que no se "italicen", entonces necesitas indicar que el asterisco no es especial. Esto se indica anteponiendo una barra invertida justo antes de él, del siguiente modo "\*", o rodeándolo dobles comillas, del siguiente modo:

``\*``

Los elementos de la lista pueden definirse de tres modos: enumerated, viñetas o símbolos y definiciones (nosotros hablaremos de los 2 primeros).

Las listas deben empezar siempre en un párrafo nuevo como éste y después de una línea en blanco.

Lista numerada (números, letras o números romanos)

Comienza un línea con un número o una letra seguida de un punto ".", un paréntesis de cierre ")" o entre paréntesis "( )" lo que resulte más cómodo. Todas las formas siguientes están reconocidas:

1. números 

A. Letras mayúsculas
   y que se dividan en varias líneas

   con dos párrafos y todo

a. letras en minúscula

   3. Con una sublista que comienza con un número diferente
   4. asegurate que los números están en la secuencia correcta

I. números romanos en mayúscula   

i. números romanos en minúscula

(1) números otra vez    

1) y otra    

el resultado es (aviso: los diferentes estilos de enumerado de listas no son soportados siempre por todos los navegadores, así puede que no surta efecto aquí):

1. números

1. Letras mayúsculas y que se dividan en varias líneas

   con dos párrafos y todo

1. letras en minúscula
   3. Con una sublista que comienza con un número diferente
   4. asegurate que los números están en la secuencia correcta

1. números romanos en mayúscula

1. números romanos en minúscula

1. números otra vez

1. y otra

Al igual que las listas enumeradas, las listas con viñetas comienzan con un carácter símbolo que puede ser "-", "+" o "*":

* una viñeta usando "*"    

  - una sub lista usando "-" 

    + otra sub lista 

  - otro elemento

El resultado es:

• una viñeta usando "*"
  • una sub lista usando "-"
    • otra sub lista
  • otro elemento

Para incluir fragmentos de texto preformateado, nunca podrá mezclarse con texto, finaliza el párrafo precedente con "::". El bloque preformateado terminará cuando el texto vuelva al mismo nivel de indentación que el párrafo anterior que no esté preformateado. Por ejemplo:

Un ejemplo::

  Espacios en blanco, líneas nuevas, líneas en blanco, y todo tipo de marcas 
    (como *esta* o \esta) serán mantenidas por los bloques preformateados o literales.
  Mira aquí, he incluido un nivel más de indentación (pero no muy lejos)

fin del ejemplo

El resultado es:

Un ejemplo:

Espacios en blanco, líneas nuevas, líneas en blanco, y todo tipo de marcas 
  (como *esta* o \esta) serán mantenidas por los bloques preformateados o literales.
Mira aquí, he incluido un nivel más de indentación (pero no muy lejos)

fin del ejemplo

Observa que si un párrafo consiste sólo en "::", entonces es borrado por la salida:

::

    Esto es texto preformateado, y el 
    último párrafo "::" es borrado

El resultado es:

Esto es texto preformateado, y el 
último párrafo "::" es borrado

Para dividir textos largos en secciones, debes usar cabeceras de sección. Estas son líneas individuales (una o más palabras con un adorno): un subrayado sólo, o un subrayado y una línea superpuesta juntos, con guiones "-----", símbolos de igual "=====", tildes "~~~~~" o cualquier caracter no alfanumérico = - ` : ' " ~ ^ _ * + # < > con el que te sientas cómodo. Un subrayado sólo es distinto a un subrayado y superpuesto usando el mismo carácter. El subrayado o el superposicionado debe ser al menos tan largo como el texto. Se consistente, todas las secciones marcadas con el mismo símbolo estarán situadas al mismo nivel:

Capítulo 1 Título
=================

Sección 1.1 Título
-------------------

Subsección 1.1.1 Título
~~~~~~~~~~~~~~~~~~~~~~~~

Sección 1.2 Título
-------------------

Capítulo 2 Título
=================

El resultado se muestra en la siguiente estructura, ilustrada para simplificar en un seudo XML:

<section>
    <title>
        Capítulo 1 Título
    <section>
        <title>
            Sección 1.1 Título
        <section>
            <title>
                Subsección 1.1.1 Título
    <section>
        <title>
            Sección 1.2 Título
<section>
    <title>
        Capítulo 2 Título

(Seudo XML usa la indentación como muestra y no tiene tags finales. Es imposible mostrar la salida actual procesada, como en otros ejemplos, porque las secciones no pueden existir dentro de bloques. Para un ejemplo concreto, compara la estructura de las secciones de este documento en el texto fuente y procesa la salida)

Nota que las cabeceras de sección están disponibles como destinos de un link, sólo usando su nombre. Para vincular a la cabecera de las 'Listas', escribo "Listas_". Si la cabecera tiene espacios en ella como 'estilos de texto', necesitamos acotar la cabecera "`estilos de texto`_".

Observaciones a tener en cuenta.

• Aunque se centre el texto en la celda de la tabla, éste no se visualizará centrado, a no ser que sea el título, en este caso si surte efecto.
• Para hacer una lista enumerada no utilices sangrías, utiliza números o letras para los apartados y para los subapartados guiones "-"

1. Enumeramos de la siguiente manera
 - Los subapartados los ponemos con guiones, el método es: (espacio, guión, espacio).
 - Escriba el texto que desee.

2. La sintaxis para insertar una tabla sería:

  +-----------------------------------------------------------+
  | **Control de versiones del manual de usuario de gvSIG**   |
  +==========================+================================+
  |                          |1. Se ha incluido la documen    |
  |                          |tación sobre la nueva ventana   |
  |                          |de salvar proyecto de gvSIG.    |
  |Manual Usuario gvSIG 1.1  |                                |
  |Versión 4                 |2. Se ha incluido documentación |
  |                          |sobre la herramienta de         |
  |                          |exportar a ráster.              |
  |                          |                                |
  |                          |3. Se ha dos errores conocidos: |
  |                          |                                |
  |                          |  - Fallo en los resultados de  |
  |                          |    las funciones de agrupamien |
  |                          |    to en el geoproceso disolver|
  |                          |  - Error conocido de la herra  |
  |                          |    mienta "Exportar a raster"  |
  +--------------------------+--------------------------------+

El resultado sería:

Además de esta forma de crear tablas en ReStructuredText, existen otras basadas en directivas. En muchas ocasiones es mas cómodo trabajar con la forma de creación de tablas basada en la directiva list-table. Consulte esto en la siguiente sección.

Las principales directivas usadas en gvsig.org son:

• contents. Permiten insertar una tabla de contenidos en el documento. Su uso seria:

  .. contents:: Titulo de la tabla de contenidos.
  

  Aunque es muy útil esta directiva, en el contexto de la generación de documentación en gvsig.org, hay que llevar especial cuidado con ella, ya que es normal que luego un documento pase a formar parte de otro documento mayor, y si este tiene insertada alguna tabla de contenidos nos la encontraremos en medio del documento que lo contenga.

• figure. Permite insertar imágenes dentro del documento.

  Una figura consiste en datos de imagen (archivo de imagen), un pie de imagen (un párrafo), y opcionalmente una leyenda

  La sintaxis para insertar una imagen sería

  .. figure:: imagenes_src/picture.png
    :align: center
    
    Este es el pie de la imagen (sólo un párrafo).
  
    La leyenda consiste en los elementos posteriores al pie. en este caso,
    la leyenda es este párrafo.
  

  y el resultado sería

  

  Este es el pie de la imagen (sólo un párrafo).

  La leyenda consiste en los elementos posteriores al pie. en este caso, la leyenda es este párrafo.

  Es recomendable dejar una línea en blanco por encima y por debajo de la figure que se quiere insertar y no indentar la línea.

  Correcto
  
  Párrafo anterior a la figure
  
  ..figure:: images_src/picture.png
  
  Párrafo posterior a la figure
  
  No recomendado
  
  Párrafo anterior a la figure
  ..figure:: images_src/picture.png
  
  Párrafo anterior a la figure
  
    ..figure:: images_src/picture.png
  

• list-table. Nos permite insertar una tabla definiéndola como una lista de dos niveles, donde el primer nivel define las lineas y el segundo los valores de las celdas de la linea.

  Veamos un ejemplo:

  .. list-table:: Frozen Delights!
     :widths: 15 10 30
     :header-rows: 1
  
     * - Treat
       - Quantity
       - Description
     * - Albatross
       - 2.99
       - On a stick!
     * -  Crunchy Frog
       - 1.49
       - If we took the bones out, it wouldn't be
         crunchy, now would it?
     * - Gannet Ripple
       - 1.99
       - On a stick!
  

  Donde cada '*' indica el comienzo de una fila y cada '-' el comienzo de una celda.

  El resultado sería

  Frozen Delights!

  Treat	Quantity	Description
  Albatross	2.99	On a stick!
  Crunchy Frog	1.49	If we took the bones out, it wouldn't be crunchy, now would it?
  Gannet Ripple	1.99	On a stick!

En el proyecto gvSIG, se han elaborado algunas directivas que pueden resultar de utilidad en la confección de la documentación. Las más usadas son:

• include-document.

  Esta directiva permite invocar un documento para que sea incluido en el documento en el que se invoca la directiva.

  La sintaxis de la directiva es

  .. include-document:: ruta-de-la-pagina-a-incluir
     :formato:
  

  El formato es opcional, si no se indica nada se entiende que debe renderizarse como 'rest'.

  Ejemplo

  .. include-document:: ./documentacion-adicional
     :rest:
  

Contenido incluido

Podemos encontrar documentacion adicional sobre ReStructuredText en:

• A ReStructuredText Primer, http://docutils.sourceforge.net/docs/user/rst/quickstart.html
• Quick reStructuredText, http://docutils.sourceforge.net/docs/user/rst/quickref.html
• reStructuredText Directives, http://docutils.sourceforge.net/docs/ref/rst/directives.html
• reStructuredText Markup Specification, http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html

Fin contenido incluido

• code-block

  Esta directiva permite "colorear" el código fuente que sigue a la directiva. La sintaxis es la siguiente

  .. code-block:: languaje
  
     My code goes here.
  

  Por ejemplo si nuestro código es python:

  .. code-block:: python
  
     class Test:
     
       def TestFunction(self):
         pass
  

Se vería así

class Test:

  def TestFunction(self):
     pass

Esta directiva también permite que se muestren los números de línea del código.

.. code-block:: python
  :linenos:
  
  # -*- coding: utf-8 -*-
  """
      The Pygments reStructuredText directive
      ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  
      This fragment is a Docutils_ 0.4 directive that renders source code
      (to HTML only, currently) via Pygments.
  
      To use it, adjust the options below and copy the code into a module
      that you import on initialization.  The code then automatically
      registers the ``code-block`` directive that you can use instead of
      normal code blocks like this::
  
          .. code-block:: python
  
              My code goes here.
  
      If you want to have different code styles, e.g. one with line numbers
      and one without, add formatters with their names in the VARIANTS dict
      below.  You can invoke them instead of the DEFAULT one by using a
      directive option::
  
          .. code-block:: python
              :linenos:
  
              My code goes here.
  
      Look at the `directive documentation`_ to get all the gory details.
  
      .. _Docutils: http://docutils.sf.net/
      .. _directive documentation:
        http://docutils.sourceforge.net/docs/howto/rst-directives.html
  
    :copyright: 2007 by Georg Brandl.
                2008 by Sergio Talens-Oliag (adaptation for the RstCodeBlock)
    :license: BSD, see LICENSE for more details.
  """
  
  # Options
  # ~~~~~~~
  
  # Set to True if you want inline CSS styles instead of classes
  INLINESTYLES = True
  
  from pygments.formatters import HtmlFormatter
  
  # The default formatter
  DEFAULT = HtmlFormatter(noclasses=INLINESTYLES)
  
  # Add name -> formatter pairs for every variant you want to use
  VARIANTS = {
      'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True),
  }
  
  from docutils import nodes
  from docutils.parsers.rst import directives
  
  from pygments import highlight
  from pygments.lexers import get_lexer_by_name, TextLexer
  
  def pygments_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state, state_machine):
      '''Implement the code-block directive for docutils.'''
      try:
          lexer = get_lexer_by_name(arguments[0])
      except ValueError:
          # no lexer found - use the text one instead of an exception
          lexer = TextLexer()
      # take an arbitrary option if more than one is given
      formatter = options and VARIANTS[options.keys()[0]] or DEFAULT
      parsed = highlight(u'\n'.join(content), lexer, formatter)
      return [nodes.raw('', parsed, format='html')]
  
  pygments_directive.arguments = (1, 0, 1)
  pygments_directive.content = 1
  pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])
  
  directives.register_directive('code-block', pygments_directive)

Se vería

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78

# -*- coding: utf-8 -*-
"""
    The Pygments reStructuredText directive
    ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

    This fragment is a Docutils_ 0.4 directive that renders source code
    (to HTML only, currently) via Pygments.

    To use it, adjust the options below and copy the code into a module
    that you import on initialization.  The code then automatically
    registers the ``code-block`` directive that you can use instead of
    normal code blocks like this::

        .. code-block:: python

            My code goes here.

    If you want to have different code styles, e.g. one with line numbers
    and one without, add formatters with their names in the VARIANTS dict
    below.  You can invoke them instead of the DEFAULT one by using a
    directive option::

        .. code-block:: python
            :linenos:

            My code goes here.

    Look at the `directive documentation`_ to get all the gory details.

    .. _Docutils: http://docutils.sf.net/
    .. _directive documentation:
       http://docutils.sourceforge.net/docs/howto/rst-directives.html

   :copyright: 2007 by Georg Brandl.
                2008 by Sergio Talens-Oliag (adaptation for the RstCodeBlock)
    :license: BSD, see LICENSE for more details.
"""

# Options
# ~~~~~~~

# Set to True if you want inline CSS styles instead of classes
INLINESTYLES = True

from pygments.formatters import HtmlFormatter

# The default formatter
DEFAULT = HtmlFormatter(noclasses=INLINESTYLES)

# Add name -> formatter pairs for every variant you want to use
VARIANTS = {
    'linenos': HtmlFormatter(noclasses=INLINESTYLES, linenos=True),
}

from docutils import nodes
from docutils.parsers.rst import directives

from pygments import highlight
from pygments.lexers import get_lexer_by_name, TextLexer

def pygments_directive(name, arguments, options, content, lineno,
                       content_offset, block_text, state, state_machine):
    '''Implement the code-block directive for docutils.'''
    try:
        lexer = get_lexer_by_name(arguments[0])
    except ValueError:
        # no lexer found - use the text one instead of an exception
        lexer = TextLexer()
    # take an arbitrary option if more than one is given
    formatter = options and VARIANTS[options.keys()[0]] or DEFAULT
    parsed = highlight(u'\n'.join(content), lexer, formatter)
    return [nodes.raw('', parsed, format='html')]

pygments_directive.arguments = (1, 0, 1)
pygments_directive.content = 1
pygments_directive.options = dict([(key, directives.flag) for key in VARIANTS])

directives.register_directive('code-block', pygments_directive)

Podemos encontrar documentacion adicional sobre ReStructuredText en:

• A ReStructuredText Primer, http://docutils.sourceforge.net/docs/user/rst/quickstart.html
• Quick reStructuredText, http://docutils.sourceforge.net/docs/user/rst/quickref.html
• reStructuredText Directives, http://docutils.sourceforge.net/docs/ref/rst/directives.html
• reStructuredText Markup Specification, http://docutils.sourceforge.net/docs/ref/rst/restructuredtext.html