1 =======================================
2 Creating reStructuredText_ Directives
3 =======================================
5 :Authors: Dethe Elza, David Goodger, Lea Wiemann
6 :Contact: docutils-develop@lists.sourceforge.net
9 :Copyright: This document has been placed in the public domain.
11 .. _reStructuredText: http://docutils.sourceforge.net/rst.html
14 Directives are the primary extension mechanism of reStructuredText.
15 This document aims to make the creation of new directives as easy and
16 understandable as possible. There are only a couple of
17 reStructuredText-specific features the developer needs to know to
18 create a basic directive.
20 The syntax of directives is detailed in the `reStructuredText Markup
21 Specification`_, and standard directives are described in
22 `reStructuredText Directives`_.
24 Directives are a reStructuredText markup/parser concept. There is no
25 "directive" document tree element, no single element that corresponds
26 exactly to the concept of directives. Instead, choose the most
27 appropriate elements from the existing Docutils elements. Directives
28 build structures using the existing building blocks. See `The
29 Docutils Document Tree`_ and the ``docutils.nodes`` module for more
30 about the building blocks of Docutils documents.
32 .. _reStructuredText Markup Specification:
33 ../ref/rst/restructuredtext.html#directives
34 .. _reStructuredText Directives: ../ref/rst/directives.html
35 .. _The Docutils Document Tree: ../ref/doctree.html
38 .. contents:: Table of Contents
44 Directives are created by defining a directive class that inherits
45 from ``docutils.parsers.rst.Directive``::
47 from docutils.parsers import rst
49 class MyDirective(rst.Directive):
53 To understand how to implement the directive, let's have a look at the
54 docstring of the ``Directive`` base class::
56 >>> from docutils.parsers import rst
57 >>> print rst.Directive.__doc__
59 Base class for reStructuredText directives.
61 The following attributes may be set by subclasses. They are
62 interpreted by the directive parser (which runs the directive
65 - `required_arguments`: The number of required arguments (default:
68 - `optional_arguments`: The number of optional arguments (default:
71 - `final_argument_whitespace`: A boolean, indicating if the final
72 argument may contain whitespace (default: False).
74 - `option_spec`: A dictionary, mapping known option names to
75 conversion functions such as `int` or `float` (default: {}, no
76 options). Several conversion functions are defined in the
77 directives/__init__.py module.
79 Option conversion functions take a single parameter, the option
80 argument (a string or ``None``), validate it and/or convert it
81 to the appropriate form. Conversion functions may raise
82 `ValueError` and `TypeError` exceptions.
84 - `has_content`: A boolean; True if content is allowed. Client
85 code must handle the case where content is required but not
86 supplied (an empty content list will be supplied).
88 Arguments are normally single whitespace-separated words. The
89 final argument may contain whitespace and/or newlines if
90 `final_argument_whitespace` is True.
92 If the form of the arguments is more complex, specify only one
93 argument (either required or optional) and set
94 `final_argument_whitespace` to True; the client code must do any
95 context-sensitive parsing.
97 When a directive implementation is being run, the directive class
98 is instantiated, and the `run()` method is executed. During
99 instantiation, the following instance variables are set:
101 - ``name`` is the directive type or name (string).
103 - ``arguments`` is the list of positional arguments (strings).
105 - ``options`` is a dictionary mapping option names (strings) to
106 values (type depends on option conversion functions; see
107 `option_spec` above).
109 - ``content`` is a list of strings, the directive content line by line.
111 - ``lineno`` is the line number of the first line of the directive.
113 - ``content_offset`` is the line offset of the first line of the content from
114 the beginning of the current input. Used when initiating a nested parse.
116 - ``block_text`` is a string containing the entire directive.
118 - ``state`` is the state which called the directive function.
120 - ``state_machine`` is the state machine which controls the state which called
121 the directive function.
123 Directive functions return a list of nodes which will be inserted
124 into the document tree at the point where the directive was
125 encountered. This can be an empty list if there is nothing to
128 For ordinary directives, the list must contain body elements or
129 structural elements. Some directives are intended specifically
130 for substitution definitions, and must return a list of `Text`
131 nodes and/or inline elements (suitable for inline insertion, in
132 place of the substitution reference). Such directives must verify
133 substitution definition context, typically using code like this::
135 if not isinstance(state, states.SubstitutionDef):
136 error = state_machine.reporter.error(
137 'Invalid context: the "%s" directive can only be used '
138 'within a substitution definition.' % (name),
139 nodes.literal_block(block_text, block_text), line=lineno)
145 Option Conversion Functions
146 ===========================
148 An option specification (``Directive.option_spec``) must be defined
149 detailing the options available to the directive. An option spec is a
150 mapping of option name to conversion function; conversion functions
151 are applied to each option value to check validity and convert them to
152 the expected type. Python's built-in conversion functions are often
153 usable for this, such as ``int``, ``float``. Other useful conversion
154 functions are included in the ``docutils.parsers.rst.directives``
155 package (in the ``__init__.py`` module):
157 - ``flag``: For options with no option arguments. Checks for an
158 argument (raises ``ValueError`` if found), returns ``None`` for
161 - ``unchanged_required``: Returns the text argument, unchanged.
162 Raises ``ValueError`` if no argument is found.
164 - ``unchanged``: Returns the text argument, unchanged. Returns an
165 empty string ("") if no argument is found.
167 - ``path``: Returns the path argument unwrapped (with newlines
168 removed). Raises ``ValueError`` if no argument is found.
170 - ``uri``: Returns the URI argument with whitespace removed. Raises
171 ``ValueError`` if no argument is found.
173 - ``nonnegative_int``: Checks for a nonnegative integer argument,
174 and raises ``ValueError`` if not.
176 - ``class_option``: Converts the argument into an ID-compatible
177 string and returns it. Raises ``ValueError`` if no argument is
180 - ``unicode_code``: Convert a Unicode character code to a Unicode
183 - ``single_char_or_unicode``: A single character is returned as-is.
184 Unicode characters codes are converted as in ``unicode_code``.
186 - ``single_char_or_whitespace_or_unicode``: As with
187 ``single_char_or_unicode``, but "tab" and "space" are also
190 - ``positive_int``: Converts the argument into an integer. Raises
191 ValueError for negative, zero, or non-integer values.
193 - ``positive_int_list``: Converts a space- or comma-separated list
194 of integers into a Python list of integers. Raises ValueError for
195 non-positive-integer values.
197 - ``encoding``: Verfies the encoding argument by lookup. Raises
198 ValueError for unknown encodings.
200 A further utility function, ``choice``, is supplied to enable
201 options whose argument must be a member of a finite set of possible
202 values. A custom conversion function must be written to use it.
205 from docutils.parsers.rst import directives
208 return directives.choice(argument, ('yes', 'no'))
210 For example, here is an option spec for a directive which allows two
211 options, "name" and "value", each with an option argument::
213 option_spec = {'name': unchanged, 'value': int}
219 If your directive implementation encounters an error during
220 processing, you should call ``self.error()`` inside the ``run()``
224 raise self.error('Error message.')
226 The ``self.error()`` method will immediately raise an exception that
227 will be caught by the reStructuredText directive handler. The
228 directive handler will then insert an error-level system message in
229 the document at the place where the directive occurred.
231 Instead of ``self.error``, you can also use ``self.severe`` and
232 ``self.warning`` for more or less severe problems.
234 If you want to return a system message *and* document contents, you need to
235 create the system message yourself instead of using the ``self.error``
240 node = nodes.paragraph(...)
241 # Node list to return.
244 # Create system message.
245 error = self.reporter.error(
246 'Error in "%s" directive: Your error message.' % self.name,
247 nodes.literal_block(block_text, block_text), line=lineno)
248 node_list.append(error)
252 Register the Directive
253 ======================
255 * If the directive is a general-use **addition to the Docutils core**,
256 it must be registered with the parser and language mappings added:
258 1. Register the new directive using its canonical name in
259 ``docutils/parsers/rst/directives/__init__.py``, in the
260 ``_directive_registry`` dictionary. This allows the
261 reStructuredText parser to find and use the directive.
263 2. Add an entry to the ``directives`` dictionary in
264 ``docutils/parsers/rst/languages/en.py`` for the directive, mapping
265 the English name to the canonical name (both lowercase). Usually
266 the English name and the canonical name are the same.
268 3. Update all the other language modules as well. For languages in
269 which you are proficient, please add translations. For other
270 languages, add the English directive name plus "(translation
273 * If the directive is **application-specific**, use the
274 ``register_directive`` function::
276 from docutils.parsers.rst import directives
277 directives.register_directive(directive_name, directive_class)
283 For the most direct and accurate information, "Use the Source, Luke!".
284 All standard directives are documented in `reStructuredText
285 Directives`_, and the source code implementing them is located in the
286 ``docutils/parsers/rst/directives`` package. The ``__init__.py``
287 module contains a mapping of directive name to module and function
288 name. Several representative directives are described below.
294 `Admonition directives`__, such as "note" and "caution", are quite
295 simple. They have no directive arguments or options. Admonition
296 directive content is interpreted as ordinary reStructuredText.
298 __ ../ref/rst/directives.html#specific-admonitions
300 The resulting document tree for a simple reStructuredText line
301 "``.. note:: This is a note.``" looks as follows:
307 The directive class for the "note" directive simply derives from a
308 generic admonition directive class::
310 class Note(BaseAdmonition):
312 node_class = nodes.note
314 Note that the only thing distinguishing the various admonition
315 directives is the element (node class) generated. In the code above,
316 the node class is set as a class attribute and is read by the
317 ``run()`` method of ``BaseAdmonition``, where the actual processing
320 # Import Docutils document tree nodes module.
321 from docutils import nodes
322 # Import Directive base class.
323 from docutils.parsers.rst import Directive
325 class BaseAdmonition(Directive):
327 required_arguments = 0
328 optional_arguments = 0
329 final_argument_whitespace = True
334 """Subclasses must set this to the appropriate admonition node class."""
337 # Raise an error if the directive does not have contents.
338 self.assert_has_content()
339 text = '\n'.join(self.content)
340 # Create the admonition node, to be populated by `nested_parse`.
341 admonition_node = self.node_class(rawsource=text)
342 # Parse the directive contents.
343 self.state.nested_parse(self.content, self.content_offset,
345 return [admonition_node]
347 Three things are noteworthy in the ``run()`` method above:
349 * The ``admonition_node = self.node_class(text)`` line creates the
350 wrapper element, using the class set by the specific admonition
351 subclasses (as in note, ``node_class = nodes.note``).
353 * The call to ``state.nested_parse()`` is what does the actual
354 processing. It parses the directive content and adds any generated
355 elements as child elements of ``admonition_node``.
357 * If there was no directive content, the ``assert_has_content()``
358 convenience method raises an error exception by calling
359 ``self.error()`` (see `Error Handling`_ above).
365 .. _image: ../ref/rst/directives.html#image
367 The "image_" directive is used to insert a picture into a document.
368 This directive has one argument, the path to the image file, and
369 supports several options. There is no directive content. Here's an
370 early version of the image directive class::
372 # Import Docutils document tree nodes module.
373 from docutils import nodes
374 # Import ``directives`` module (contains conversion functions).
375 from docutils.parsers.rst import directives
376 # Import Directive base class.
377 from docutils.parsers.rst import Directive
380 """Conversion function for the "align" option."""
381 return directives.choice(argument, ('left', 'center', 'right'))
383 class Image(Directive):
385 required_arguments = 1
386 optional_arguments = 0
387 final_argument_whitespace = True
388 option_spec = {'alt': directives.unchanged,
389 'height': directives.nonnegative_int,
390 'width': directives.nonnegative_int,
391 'scale': directives.nonnegative_int,
397 reference = directives.uri(self.arguments[0])
398 self.options['uri'] = reference
399 image_node = nodes.image(rawsource=self.block_text,
403 Several things are noteworthy in the code above:
405 * The "image" directive requires a single argument, which is allowed
406 to contain whitespace (``final_argument_whitespace = True``). This
407 is to allow for long URLs which may span multiple lines. The first
408 line of the ``run()`` method joins the URL, discarding any embedded
411 * The reference is added to the ``options`` dictionary under the
412 "uri" key; this becomes an attribute of the ``nodes.image`` element
413 object. Any other attributes have already been set explicitly in
414 the reStructuredText source text.
420 Directives that cause actions to be performed *after* the complete
421 document tree has been generated can be implemented using a
422 ``pending`` node. The ``pending`` node causes a transform_ to be run
423 after the document has been parsed.
425 For an example usage of the ``pending`` node, see the implementation
426 of the ``contents`` directive in
427 docutils.parsers.rst.directives.parts__.
429 .. _transform: ../ref/transforms.html
430 __ http://docutils.sf.net/docutils/parsers/rst/directives/parts.py