1 ==================================================
2 Creating reStructuredText Interpreted Text Roles
3 ==================================================
5 :Authors: David Goodger
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
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.
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.
19 .. _reStructuredText Interpreted Text Roles: ../ref/rst/roles.html
21 ../ref/rst/restructuredtext.html#interpreted-text
22 .. _reStructuredText Markup Specification:
23 ../ref/rst/restructuredtext.html
29 Define the Role Function
30 ========================
32 The role function creates and returns inline elements (nodes) and does
33 any additional processing required. Its signature is as follows::
35 def role_fn(name, rawtext, text, lineno, inliner,
36 options={}, content=[]):
39 # Set function attributes for customization:
43 Function attributes are described below (see `Specify Role Function
44 Options and Content`_). The role function parameters are as follows:
46 * ``name``: The local name of the interpreted role, the role name
47 actually used in the document.
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.
53 * ``text``: The interpreted text content.
55 * ``lineno``: The line number where the interpreted text begins.
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.
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.
66 * ``content``: A list of strings, the directive content for
67 customization (from the `"role" directive`_). To be interpreted by
70 Role functions return a tuple of two values:
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
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).
80 Specify Role Function Options and Content
81 =========================================
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
88 - ``options``: The option specification. All role functions
89 implicitly support the "class" option, unless disabled with an
90 explicit ``{'class': None}``.
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`_.
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).
106 As of this writing, no roles accept directive content.
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.
112 .. _"role" directive: ../ref/rst/directives.html#role
113 .. _Creating reStructuredText Directives:
114 rst-directives.html#specify-directive-arguments-options-and-content
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:
123 1. Register the new role using the canonical name::
125 from docutils.parsers.rst import roles
126 roles.register_canonical_role(name, role_function)
128 This code is normally placed immediately after the definition of
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.
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)".
141 If the role is application-specific, use the ``register_local_role``
144 from docutils.parsers.rst import roles
145 roles.register_local_role(name, role_function)
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.
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::
165 register_generic_role('emphasis', nodes.emphasis)
167 For the implementation of ``register_generic_role``, see the
168 ``docutils.parsers.rst.roles`` module.
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::
179 See :RFC:`2822` for information about email headers.
181 This is equivalent to::
183 See `RFC 2822`__ for information about email headers.
185 __ http://www.faqs.org/rfcs/rfc2822.html
187 Here is the implementation of the role::
189 def rfc_reference_role(role, rawtext, text, lineno, inliner,
190 options={}, content=[]):
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)
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
204 node = nodes.reference(rawtext, 'RFC ' + utils.unescape(text), refuri=ref,
208 register_canonical_role('rfc-reference', rfc_reference_role)
210 Noteworthy in the code above are:
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.
219 2. The RFC reference itself is constructed from a stock URI, set as
220 the "refuri" attribute of a "reference" element.
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.
228 .. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search