docutils.parsers.rst

package documentation

This is docutils.parsers.rst package. It exports a single class, Parser, the reStructuredText parser.

Usage

Create a parser:
```
parser = docutils.parsers.rst.Parser()
```
Several optional arguments may be passed to modify the parser's behavior. Please see Customizing the Parser below for details.
Gather input (a multi-line string), by reading a file or the standard input:
```
input = sys.stdin.read()
```
Create a new empty docutils.nodes.document tree:
```
document = docutils.utils.new_document(source, settings)
```
See docutils.utils.new_document() for parameter details.
Run the parser, populating the document tree:
```
parser.parse(input, document)
```

Parser Overview

The reStructuredText parser is implemented as a state machine, examining its input one line at a time. To understand how the parser works, please first become familiar with the docutils.statemachine module, then see the states module.

Customizing the Parser

Anything that isn't already customizable is that way simply because that type of customizability hasn't been implemented yet. Patches welcome!

When instantiating an object of the Parser class, two parameters may be passed: rfc2822 and inliner. Pass rfc2822=True to enable an initial RFC-2822 style header block, parsed as a "field_list" element (with "class" attribute set to "rfc2822"). Currently this is the only body-level element which is customizable without subclassing. (Tip: subclass Parser and change its "state_classes" and "initial_state" attributes to refer to new classes. Contact the author if you need more details.)

The inliner parameter takes an instance of states.Inliner or a subclass. It handles inline markup recognition. A common extension is the addition of further implicit hyperlinks, like "RFC 2822". This can be done by subclassing states.Inliner, adding a new method for the implicit markup, and adding a (pattern, method) pair to the "implicit_dispatch" attribute of the subclass. See states.Inliner.implicit_inline() for details. Explicit inline markup can be customized in a states.Inliner subclass via the patterns.initial and dispatch attributes (and new methods as appropriate).

Package	`directives`	This package contains directive implementation modules.
Package	`languages`	This package contains modules for language-dependent features of reStructuredText.
Module	`roles`	This module defines standard interpreted text role functions, a registry for interpreted text roles, and an API for adding to and retrieving from the registry. See also `Creating reStructuredText Interpreted Text Roles`__.
Module	`states`	This is the `docutils.parsers.rst.states` module, the core of the reStructuredText parser. It defines the following:
Module	`tableparser`	This module defines table parser classes,which parse plaintext-graphic tables and produce a well-formed data structure suitable for building a CALS table.

From __init__.py:

Class	`Directive`	Base class for reStructuredText directives.
Class	`DirectiveError`	Store a message and a system message level.
Class	`Parser`	The reStructuredText parser.
Function	`convert_directive_function`	Define & return a directive class generated from `directive_fn`.

def convert_directive_function(directive_fn):

Define & return a directive class generated from directive_fn.

directive_fn uses the old-style, functional interface.