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)