1
==================================================
2
Creating reStructuredText Interpreted Text Roles
3
==================================================
5
:Authors: David Goodger
6
:Contact: goodger@python.org
7
:Date: $Date: 2004/04/27 20:20:59 $
8
:Revision: $Revision: 1.3 $
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: ../rst/interpreted.html
20
.. _Interpreted Text: ../rst/reStructuredText.html#interpreted-text
21
.. _reStructuredText Markup Specification: ../rst/reStructuredText.html
27
Define the Role Function
28
========================
30
The role function creates and returns inline elements (nodes) and does
31
any additional processing required. Its signature is as follows::
33
def role_fn(name, rawtext, text, lineno, inliner,
34
options={}, content=[]):
37
# Set function attributes for customization:
41
Function attributes are described below (see `Specify Role Function
42
Options and Content`_). The role function parameters are as follows:
44
* ``name``: The local name of the interpreted role, the role name
45
actually used in the document.
47
* ``rawtext``: A string containing the enitre interpreted text input,
48
including the role and markup. Return it as a ``problematic`` node
49
linked to a system message if a problem is encountered.
51
* ``text``: The interpreted text content.
53
* ``lineno``: The line number where the interpreted text begins.
55
* ``inliner``: The ``docutils.parsers.rst.states.Inliner`` object that
56
called role_fn. It contains the several attributes useful for error
57
reporting and document tree access.
59
* ``options``: A dictionary of directive options for customization
60
(from the `"role" directive`_), to be interpreted by the role
61
function. Used for additional attributes for the generated elements
62
and other functionality.
64
* ``content``: A list of strings, the directive content for
65
customization (from the `"role" directive`_). To be interpreted by
68
Role functions return a tuple of two values:
70
* A list of nodes which will be inserted into the document tree at the
71
point where the interpreted role was encountered (can be an empty
74
* A list of system messages, which will be inserted into the document tree
75
immediately after the end of the current block (can also be empty).
78
Specify Role Function Options and Content
79
=========================================
81
Function attributes are for customization, and are interpreted by the
82
`"role" directive`_. If unspecified, role function attributes are
83
assumed to have the value ``None``. Two function attributes are
86
- ``options``: The option specification. All role functions
87
implicitly support the "class" option, unless disabled with an
88
explicit ``{'class': None}``.
90
An option specification must be defined detailing the options
91
available to the "role" directive. An option spec is a mapping of
92
option name to conversion function; conversion functions are applied
93
to each option value to check validity and convert them to the
94
expected type. Python's built-in conversion functions are often
95
usable for this, such as ``int``, ``float``, and ``bool`` (included
96
in Python from version 2.2.1). Other useful conversion functions
97
are included in the ``docutils.parsers.rst.directives`` package.
98
For further details, see `Creating reStructuredText Directives`_.
100
- ``content``: A boolean; true if "role" directive content is allowed.
101
Role functions must handle the case where content is required but
102
not supplied (an empty content list will be supplied).
104
As of this writing, no roles accept directive content.
106
Note that unlike directives, the "arguments" function attribute is not
107
supported for role customization. Directive arguments are handled by
108
the "role" directive itself.
110
.. _"role" directive: directives.html#role
111
.. _Creating reStructuredText Directives:
112
rst-directives.html#specify-directive-arguments-options-and-content
118
If the role is a general-use addition to the Docutils core, it must be
119
registered with the parser and language mappings added:
121
1. Register the new role using the canonical name::
123
from docutils.parsers.rst import roles
124
roles.register_canonical_role(name, role_function)
126
This code is normally placed immediately after the definition of
129
2. Add an entry to the ``roles`` dictionary in
130
``docutils/parsers/rst/languages/en.py`` for the role, mapping the
131
English name to the canonical name (both lowercase). Usually the
132
English name and the canonical name are the same. Abbreviations
133
and other aliases may also be added here.
135
3. Update all the other language modules as well. For languages in
136
which you are proficient, please add translations. For other
137
languages, add the English role name plus "(translation required)".
139
If the role is application-specific, use the ``register_local_role``
142
from docutils.parsers.rst import roles
143
roles.register_local_role(name, role_function)
149
For the most direct and accurate information, "Use the Source, Luke!".
150
All standard roles are documented in `reStructuredText Interpreted
151
Text Roles`_, and the source code implementing them is located in the
152
``docutils/parsers/rst/roles.py`` module. Several representative
153
roles are described below.
159
Many roles simply wrap a given element around the text. There's a
160
special helper function, ``register_generic_role``, which generates a
161
role function from the canonical role name and node class::
163
register_generic_role('emphasis', nodes.emphasis)
165
For the implementation of ``register_generic_role``, see the
166
``docutils.parsers.rst.roles`` module.
172
This role allows easy references to RFCs_ (Request For Comments
173
documents) by automatically providing the base URL,
174
http://www.faqs.org/rfcs/, and appending the RFC document itself
175
(rfcXXXX.html, where XXXX is the RFC number). For example::
177
See :RFC:`2822` for information about email headers.
179
This is equivalent to::
181
See `RFC 2822`__ for information about email headers.
183
__ http://www.faqs.org/rfcs/rfc2822.html
185
Here is the implementation of the role::
187
def rfc_reference_role(role, rawtext, text, lineno, inliner,
188
options={}, content=[]):
194
msg = inliner.reporter.error(
195
'RFC number must be a number greater than or equal to 1; '
196
'"%s" is invalid.' % text, line=lineno)
197
prb = inliner.problematic(rawtext, rawtext, msg)
199
# Base URL mainly used by inliner.rfc_reference, so this is correct:
200
ref = inliner.rfc_url % rfcnum
201
node = nodes.reference(rawtext, 'RFC ' + text, refuri=ref, **options)
204
register_canonical_role('rfc-reference', rfc_reference_role)
206
Noteworthy in the code above are:
208
1. The interpreted text itself should contain the RFC number. The
209
``try`` clause verifies by converting it to an integer. If the
210
conversion fails, the ``except`` clause is executed: a system
211
message is generated, the entire interpreted text construct (in
212
``rawtext``) is wrapped in a ``problematic`` node (linked to the
213
system message), and the two are returned.
215
2. The RFC reference itself is constructed from a stock URI, set as
216
the "refuri" attribute of a "reference" element.
218
3. The ``options`` function parameter, a dictionary, may contain a
219
"class" customization attribute; it is passed through to the
220
"reference" element node constructor.
222
.. _RFCs: http://foldoc.doc.ic.ac.uk/foldoc/foldoc.cgi?query=rfc&action=Search&sourceid=Mozilla-search
added
removed
spec/howto/rst-roles.txt
