Module epydoc.markup.restructuredtext

Epydoc parser for ReStructuredText strings. ReStructuredText is the standard markup language used by the Docutils project. parse_docstring() provides the primary interface to this module; it returns a ParsedRstDocstring, which supports all of the methods defined by ParsedDocstring.

ParsedRstDocstring is basically just a ParsedDocstring wrapper for the docutils.nodes.document class.

Creating `ParsedRstDocstring`s

ParsedRstDocstrings are created by the parse_document function, using the docutils.core.publish_string() method, with the following helpers:

An _EpydocReader is used to capture all error messages as it parses the docstring.
A _DocumentPseudoWriter is used to extract the document itself, without actually writing any output. The document is saved for further processing. The settings for the writer are copied from docutils.writers.html4css1.Writer, since those settings will be used when we actually write the docstring to html.

Using `ParsedRstDocstring`s

ParsedRstDocstrings support all of the methods defined by ParsedDocstring; but only the following four methods have non-default behavior:

to_html() uses an _EpydocHTMLTranslator to translate the ParsedRstDocstring's document into an HTML segment.
split_fields() uses a _SplitFieldsTranslator to divide the ParsedRstDocstring's document into its main body and its fields. Special handling is done to account for consolidated fields.
summary() uses a _SummaryExtractor to extract the first sentence from the ParsedRstDocstring's document.
to_plaintext() uses document.astext() to convert the ParsedRstDocstring's document to plaintext.

To Do: Add ParsedRstDocstring.to_latex()

Classes
`ParsedRstDocstring`	An encoded version of a ReStructuredText docstring.
`_DocumentPseudoWriter`	A pseudo-writer for the docutils framework, that can be used to access the document itself.
`_EpydocHTMLTranslator`
`_EpydocReader`	A reader that captures all errors that are generated by parsing, and appends them to a list.
`_SplitFieldsTranslator`	A docutils translator that removes all fields from a document, and collects them into the instance variable `fields`
`_SummaryExtractor`	A docutils node visitor that extracts the first sentence from the first paragraph in a document.

Function Summary
`ParsedDocstring`	`parse_docstring(docstring, errors, **options)` Parse the given docstring, which is formatted using ReStructuredText; and return a `ParsedDocstring` representation of its contents.

Variable Summary
`dict`	`CONSOLIDATED_FIELDS`: A dictionary encoding the set of 'consolidated fields' that can be used.

Function Details

parse_docstring(docstring, errors, **options)

Parse the given docstring, which is formatted using ReStructuredText; and return a ParsedDocstring representation of its contents.

Parameters:: docstring - The docstring to parse
(type=string); errors - A list where any errors generated during parsing will be stored.
(type=list of ParseError); options - Extra options. Unknown options are ignored. Currently, no extra options are defined.

Returns:: ParsedDocstring

Variable Details

CONSOLIDATED_FIELDS

A dictionary encoding the set of 'consolidated fields' that can be used. Each consolidated field is marked by a single tag, and contains a single bulleted list, where each list item starts with an identifier, marked as interpreted text (`...`). This module automatically splits these consolidated fields into individual fields. The keys of CONSOLIDATED_FIELDS are the names of possible consolidated fields; and the values are the names of the field tags that should be used for individual entries in the list.

Type:: dict
Value:: {'arguments': 'arg', 'cvariables': 'cvar', 'exceptions': 'except', 'groups': 'group', 'ivariables': 'ivar', 'keywords': 'keyword', 'parameters': 'param', 'types': 'type', ...

Generated by Epydoc 2.1 on Sat Mar 20 17:46:13 2004

http://epydoc.sf.net

Module epydoc.markup.restructuredtext

Creating ParsedRstDocstrings

Using ParsedRstDocstrings

parse_docstring(docstring, errors, **options)

CONSOLIDATED_FIELDS

Creating `ParsedRstDocstring`s

Using `ParsedRstDocstring`s