Create a parser:: parser = () Several optional arguments may be passed to modify the parser’s behavior. Please see. reStructuredText (RST, ReST, or reST) is a file format for textual data used primarily in the Python programming language community for technical documentation. It is part of the Docutils project of the Python Doc-SIG ( Documentation. RST is a file format formely created by Python community to write documentation (and so, is part of Docutils). RST files are simple text files with lightweight syntax.

Author: Vudozshura Nirn
Country: Denmark
Language: English (Spanish)
Genre: History
Published (Last): 1 May 2008
Pages: 237
PDF File Size: 1.88 Mb
ePub File Size: 9.69 Mb
ISBN: 817-5-54390-570-3
Downloads: 4102
Price: Free* [*Free Regsitration Required]
Uploader: Vudora

Directives are the primary extension mechanism of reStructuredText. This document aims to make the creation of new directives as easy and understandable as possible. There are only a rxt of reStructuredText-specific features the developer needs to know to create a basic directive. The syntax of directives is detailed in the reStructuredText Markup Specificationand standard directives are described in reStructuredText Directives.

Instead, choose the most appropriate elements from the existing Docutils elements. Directives build structures using the existing building blocks. See The Docutils Document Tree and the docutils. Directives are created by docurils a directive class that inherits from docutils.

An option specification Directive. An option spec is a mapping of option name to conversion function; conversion functions are applied to each option value to check validity and convert them to the expected type.

Other useful conversion functions are included in the docutils. A further utility function, choiceis supplied to enable options whose argument must be a member of a finite set of possible values. A custom conversion function must be written to use it. If your directive implementation encounters an error during processing, you should call self.

The directive handler will then insert an error-level system message in the document at the place where the directive occurred. If you want to return a system message and document contents, you need to create the system message yourself instead of using the self. If the directive is a general-use addition to the Docutils coreit must be registered with the rsg and language mappings added:.


Several representative directives are described below. They have no directive arguments or options. Admonition directive content is interpreted as ordinary reStructuredText. This is a note. Note that the only thing distinguishing the various admonition directives is the element node class generated. In the code above, the node class is set as a class attribute and is read by the run method of BaseAdmonitionwhere the actual processing takes place:.

Three things are noteworthy in the run method above:. This directive has one argument, the dst to the image file, and supports several options. There is no directive content. Directives that cause actions to be performed after the complete document tree has been generated can be implemented using a pending node.

The pending node causes a transform to be run after the document has been parsed. For an example rts of the pending node, see the implementation of the contents directive in docutils.


Incremental Text Examples 3: Small Text Example Themes: Large Text Example Themes: Or Not To Do? This document has been placed in the public domain. The following attributes may be set by subclasses. They are interpreted by the directive parser which runs the directive class: The number of required arguments default: The number of optional arguments default: A boolean, indicating if the final argument may contain whitespace default: A boolean; True if content is allowed.

Client code must handle dovutils case where content is required but not supplied an empty content list will be supplied. Arguments are normally single whitespace-separated words.


Source code for docutils.parsers.rst

During instantiation, the following instance variables are set: Used when initiating a nested parse. Directive functions return a list of nodes which will be inserted into the document tree at the point where the directive was encountered. This can be an empty list if there is nothing to insert. For ordinary directives, the list must contain body elements or structural elements.

Such directives must verify substitution definition context, typically using code like this:: For options with no option arguments. Checks for an argument raises ValueError if foundreturns None for valid flag options.

Returns the text argument, unchanged. Raises ValueError if no argument is found. Returns the path argument unwrapped with newlines removed. Returns the URI argument with whitespace removed. Checks for a nonnegative integer argument, and raises ValueError if not.

Converts the argument into an ID-compatible string and returns it. Convert a Unicode character code to a Unicode character. A single character is returned as-is. Converts the argument into an integer. Docutild ValueError for negative, zero, or non-integer values. Converts a space- or comma-separated list of integers into a Python list of integers.

Raises ValueError for non-positive-integer values. Verfies the encoding argument by lookup. Vocutils ValueError for unknown encodings. Node list to return.

This allows the reStructuredText parser to find and use the directive. Usually the English name and the canonical name are the same. Update all the other language modules as well.

For languages in which you are proficient, please add translations. Import Docutils document tree nodes module. Raise an error if the directive does not have rat.

Read the Docs v: