docs/howto/rst-roles.txt

   1 ==================================================
   2  Creating reStructuredText Interpreted Text Roles
   3 ==================================================
   4
   5 :Authors: David Goodger
   6 :Contact: docutils-develop@lists.sourceforge.net
   7 :Date: $Date$
   8 :Revision: $Revision$
   9 :Copyright: This document has been placed in the public domain.
  10
  11 Interpreted text roles are an extension mechanism for inline markup in
  12 reStructuredText.  This document aims to make the creation of new
  13 roles as easy and understandable as possible.
  14
  15 Standard roles are described in `reStructuredText Interpreted Text
  16 Roles`_.  See the `Interpreted Text`_ section in the `reStructuredText
  17 Markup Specification`_ for syntax details.
  18
  19 .. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html
  20 .. _Interpreted Text:
  21    ../ref/rst/restructuredtext.html#interpreted-text
  22 .. _reStructuredText Markup Specification:
  23    ../ref/rst/restructuredtext.html
  24
  25
  26 .. contents::
  27
  28
  29 Define the Role Function
  30 ========================
  31
  32 The role function creates and returns inline elements (nodes) and does
  33 any additional processing required.  Its signature is as follows::
  34
  35     def role_fn(name, rawtext, text, lineno, inliner,
  36                 options={}, content=[]):
  37         code...
  38
  39     # Set function attributes for customization:
  40     role_fn.options = ...
  41     role_fn.content = ...
  42
  43 Function attributes are described below (see `Specify Role Function
  44 Options and Content`_).  The role function parameters are as follows:
  45
  46 * ``name``: The local name of the interpreted role, the role name
  47   actually used in the document.
  48
  49 * ``rawtext``: A string containing the enitre interpreted text input,
  50   including the role and markup.  Return it as a ``problematic`` node
  51   linked to a system message if a problem is encountered.
  52
  53 * ``text``: The interpreted text content.
  54
  55 * ``lineno``: The line number where the interpreted text begins.
  56
  57 * ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that
  58   called role_fn.  It contains the several attributes useful for error
  59   reporting and document tree access.
  60
  61 * ``options``: A dictionary of directive options for customization
  62   (from the `"role" directive`_), to be interpreted by the role
  63   function.  Used for additional attributes for the generated elements
  64   and other functionality.
  65
  66 * ``content``: A list of strings, the directive content for
  67   customization (from the `"role" directive`_).  To be interpreted by
  68   the role function.
  69
  70 Role functions return a tuple of two values:
  71
  72 * A list of nodes which will be inserted into the document tree at the
  73   point where the interpreted role was encountered (can be an empty
  74   list).
  75
  76 * A list of system messages, which will be inserted into the document tree
  77   immediately after the end of the current block (can also be empty).
  78
  79
  80 Specify Role Function Options and Content
  81 =========================================
  82
  83 Function attributes are for customization, and are interpreted by the
  84 `"role" directive`_.  If unspecified, role function attributes are
  85 assumed to have the value ``None``.  Two function attributes are
  86 recognized:
  87
  88 - ``options``: The option specification.  All role functions
  89   implicitly support the "class" option, unless disabled with an
  90   explicit ``{'class': None}``.
  91
  92   An option specification must be defined detailing the options
  93   available to the "role" directive.  An option spec is a mapping of
  94   option name to conversion function; conversion functions are applied
  95   to each option value to check validity and convert them to the
  96   expected type.  Python's built-in conversion functions are often
  97   usable for this, such as ``int``, ``float``, and ``bool`` (included
  98   in Python from version 2.2.1).  Other useful conversion functions
  99   are included in the ``docutils.parsers.rst.directives`` package.
 100   For further details, see `Creating reStructuredText Directives`_.
 101
 102 - ``content``: A boolean; true if "role" directive content is allowed.
 103   Role functions must handle the case where content is required but
 104   not supplied (an empty content list will be supplied).
 105
 106   As of this writing, no roles accept directive content.
 107
 108 Note that unlike directives, the "arguments" function attribute is not
 109 supported for role customization.  Directive arguments are handled by
 110 the "role" directive itself.
 111
 112 .. _"role" directive: ../ref/rst/directives.html#role
 113 .. _Creating reStructuredText Directives:
 114    rst-directives.html#specify-directive-arguments-options-and-content
 115
 116
 117 Register the Role
 118 =================
 119
 120 If the role is a general-use addition to the Docutils core, it must be
 121 registered with the parser and language mappings added:
 122
 123 1. Register the new role using the canonical name::
 124
 125        from docutils.parsers.rst import roles
 126        roles.register_canonical_role(name, role_function)
 127
 128    This code is normally placed immediately after the definition of
 129    the role function.
 130
 131 2. Add an entry to the ``roles`` dictionary in
 132    ``docutils/parsers/rst/languages/en.py`` for the role, mapping the
 133    English name to the canonical name (both lowercase).  Usually the
 134    English name and the canonical name are the same.  Abbreviations
 135    and other aliases may also be added here.
 136
 137 3. Update all the other language modules as well.  For languages in
 138    which you are proficient, please add translations.  For other
 139    languages, add the English role name plus "(translation required)".
 140
 141 If the role is application-specific, use the ``register_local_role``
 142 function::
 143
 144     from docutils.parsers.rst import roles
 145     roles.register_local_role(name, role_function)
 146
 147
 148 Examples
 149 ========
 150
 151 For the most direct and accurate information, "Use the Source, Luke!".
 152 All standard roles are documented in `reStructuredText Interpreted
 153 Text Roles`_, and the source code implementing them is located in the
 154 ``docutils/parsers/rst/roles.py`` module.  Several representative
 155 roles are described below.
 156
 157
 158 Generic Roles
 159 -------------
 160
 161 Many roles simply wrap a given element around the text.  There's a
 162 special helper function, ``register_generic_role``, which generates a
 163 role function from the canonical role name and node class::
 164
 165     register_generic_role('emphasis', nodes.emphasis)
 166
 167 For the implementation of ``register_generic_role``, see the
 168 ``docutils.parsers.rst.roles`` module.
 169
 170
 171 RFC Reference Role
 172 ------------------
 173
 174 This role allows easy references to RFCs_ (Request For Comments
 175 documents) by automatically providing the base URL,
 176 http://www.faqs.org/rfcs/, and appending the RFC document itself
 177 (rfcXXXX.html, where XXXX is the RFC number).  For example::
 178
 179     See :RFC:`2822` for information about email headers.
 180
 181 This is equivalent to::
 182
 183     See `RFC 2822`__ for information about email headers.
 184
 185     __ http://www.faqs.org/rfcs/rfc2822.html
 186
 187 Here is the implementation of the role::
 188
 189     def rfc_reference_role(role, rawtext, text, lineno, inliner,
 190                            options={}, content=[]):
 191         try:
 192             rfcnum = int(text)
 193             if rfcnum <= 0:
 194                 raise ValueError
 195         except ValueError:
 196             msg = inliner.reporter.error(
 197                 'RFC number must be a number greater than or equal to 1; '
 198                 '"%s" is invalid.' % text, line=lineno)
 199             prb = inliner.problematic(rawtext, rawtext, msg)
 200             return [prb], [msg]
 201         # Base URL mainly used by inliner.rfc_reference, so this is correct:
 202         ref = inliner.document.settings.rfc_base_url + inliner.rfc_url % rfcnum
 203         set_classes(options)
 204         node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
 205                                **options)
 206         return [node], []
 207
 208     register_canonical_role('rfc-reference', rfc_reference_role)
 209
 210 Noteworthy in the code above are:
 211
 212 1. The interpreted text itself should contain the RFC number.  The
 213    ``try`` clause verifies by converting it to an integer.  If the
 214    conversion fails, the ``except`` clause is executed: a system
 215    message is generated, the entire interpreted text construct (in
 216    ``rawtext``) is wrapped in a ``problematic`` node (linked to the
 217    system message), and the two are returned.
 218
 219 2. The RFC reference itself is constructed from a stock URI, set as
 220    the "refuri" attribute of a "reference" element.
 221
 222 3. The ``options`` function parameter, a dictionary, may contain a
 223    "class" customization attribute; it is interpreted and replaced
 224    with a "classes" attribute by the ``set_classes()`` function.  The
 225    resulting "classes" attribute is passed through to the "reference"
 226    element node constructor.
 227
 228 .. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search