Home       Trees       Index       Help   

Docutils

Package docutils :: Package parsers :: Package rst
[show private | hide private]
[frames | no frames]

Package docutils.parsers.rst

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

Usage

  1. 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.

  2. Gather input (a multi-line string), by reading a file or the standard input:

    input = sys.stdin.read()

  3. Create a new empty docutils.nodes.document tree:

    document = docutils.utils.new_document(source, settings)

    See docutils.utils.new_document() for parameter details.

  4. 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=1 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).

Submodules
  • directives: This package contains directive implementation modules.
    • admonitions: Admonition directives.
    • body: Directives for additional body elements.
    • html: Directives for typically HTML-specific constructs.
    • images: Directives for figures and simple images.
    • misc: Miscellaneous directives.
    • parts: Directives for document parts.
    • references: Directives for references and targets.
  • languages: This package contains modules for language-dependent features of reStructuredText.
    • de: German-language mappings for language-dependent features of reStructuredText.
    • en: English-language mappings for language-dependent features of reStructuredText.
    • es: Spanish-language mappings for language-dependent features of reStructuredText.
    • fr: French-language mappings for language-dependent features of reStructuredText.
    • it: Italian-language mappings for language-dependent features of reStructuredText.
    • sk: Slovak-language mappings for language-dependent features of reStructuredText.
    • sv: Swedish language mappings for language-dependent features of reStructuredText.
  • states: This is the docutils.parsers.restructuredtext.states module, the core of the reStructuredText parser.
  • 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.

Classes
Parser The reStructuredText parser.

   Home       Trees       Index       Help   

Docutils

Generated by Epydoc 2.0 on Tue Jul 22 05:30:45 2003 http://epydoc.sf.net