Personal tools
You are here: Home gvSIG Projects gvSIG Desktop Documentation Developers documentation How to document guide El formato ReStructuredText Directivas especificas de gvsig.org
gvSIG Desktop
gvSIG Desktop

Cached time 11/21/13 11:24:39 Clear cache and reload

 

Note

En construcción

Falta incluir ejemplos y una breve descripción de cada directiva.

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:

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)

Powered by Plone CMS, the Open Source Content Management System

This site conforms to the following standards: