1
==================================================
2
Creating reStructuredText Interpreted Text Roles
3
==================================================
5
:Authors: David Goodger
6
:Contact: goodger@python.org
7
:Date: $Date: 2005-05-28 01:30:32 +0200 (Sat, 28 May 2005) $
8
:Revision: $Revision: 3394 $
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
added
removed
docs/howto/rst-roles.txt
