epydoc.markup.restructuredtext

Package epydoc :: Package markup :: Module restructuredtext |
[show private | hide private]
[frames | no frames]

## 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

`ParsedRstDocstring`s 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

`ParsedRstDocstring`s 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