epydoc.markup.ParsedDocstring

Package epydoc :: Package markup :: Class ParsedDocstring |
[show private | hide private]
[frames | no frames]

## Class ParsedDocstring

Known Subclasses:
  `ParsedEpytextDocstring`, `ParsedJavadocDocstring`, `ParsedPlaintextDocstring`, `ParsedRstDocstring`

A standard intermediate representation for parsed docstrings that can be used to generate output. Parsed docstrings are produced by markup parsers (such as `epytext.parse` or `javadoc.parse`). `ParsedDocstring`s support several kinds of operation:

- output generation (`to_plaintext()`, `to_html()`, and `to_latex()`).
- Summarization (`summary()`).
- Field extraction (`split_fields()`).
- Index term extraction (`index_terms()`.

The output generation methods (`to_format()`) use a `DocstringLinker` to link the docstring output with the rest of the documentation that epydoc generates.

# Subclassing

The only method that a subclass is required to implement is `to_plaintext()`; but it is often useful to override the other methods. The default behavior of each method is described below:

- `to_format`: Calls `to_plaintext`, and uses the string it returns to generate verbatim output.
- `summary`: Returns `self` (i.e., the entire docstring).
- `split_fields`: Returns `(self, [])` (i.e., extracts no fields).
- `index_terms`: Returns `[]` (i.e., extracts no index terms).

If and when epydoc adds more output formats, new `to_format` methods will be added to this base class; but they will always be given a default implementation.

Method Summary
| `__add__(self, other)`
| ``concatenate`(self, other)` Return a new parsed docstring containing the concatination of this docstring and `other`.
`list` of `ParsedDocstring` | ``index_terms`(self)` Return the list of index terms that are defined in this docstring.
`(`ParsedDocstring`, list of `Field`)` | ``split_fields`(self, errors)` Split this docstring into its body and its fields.
`ParsedDocstring` | ``summary`(self)` Return a short summary of this docstring.
`string` | ``to_html`(self, docstring_linker, **options)` Translate this docstring to HTML.
`string` | ``to_latex`(self, docstring_linker, **options)` Translate this docstring to LaTeX.
`string` | ``to_plaintext`(self, docstring_linker, **options)` Translate this docstring to plaintext.

Method Details

### concatenate(self, other) Returns: A new parsed docstring containing the concatination of this docstring and `other`. Raises: `ValueError` - If the two parsed docstrings are incompatible.

### index_terms(self) Returns: The list of index terms that are defined in this docstring. Each of these items will be added to the index page of the documentation. (type=`list` of `ParsedDocstring`)

### split_fields(self, errors=None) Split this docstring into its body and its fields. Parameters: `errors` - A list where any errors generated during splitting will be stored. If no list is specified, then errors will be ignored. (type=`list` of `ParseError`) Returns: A tuple `(body, fields)`, where `body` is the main body of this docstring, and `fields` is a list of its fields. (type=`(`ParsedDocstring`, list of `Field`)`)

### summary(self) Returns: A short summary of this docstring. Typically, the summary consists of the first sentence of the docstring. (type=`ParsedDocstring`)

### to_html(self, docstring_linker, **options) Translate this docstring to HTML. Parameters: `docstring_linker` - An HTML translator for crossreference links into and out of the docstring. (type=`DocstringLinker`) `options` - Any extra options for the output. Unknown options are ignored. Returns: An HTML fragment that encodes this docstring. (type=`string`)

### to_latex(self, docstring_linker, **options) Translate this docstring to LaTeX. Parameters: `docstring_linker` - A LaTeX translator for crossreference links into and out of the docstring. (type=`DocstringLinker`) `options` - Any extra options for the output. Unknown options are ignored. Returns: A LaTeX fragment that encodes this docstring. (type=`string`)

### to_plaintext(self, docstring_linker, **options) Translate this docstring to plaintext. Parameters: `docstring_linker` - A plaintext translator for crossreference links into and out of the docstring. (type=`DocstringLinker`) `options` - Any extra options for the output. Unknown options are ignored. Returns: A plaintext fragment that encodes this docstring. (type=`string`)

Generated by Epydoc 2.1 on Sat Mar 20 17:46:17 2004 | http://epydoc.sf.net