Package epydoc :: Package markup :: Class ParsedDocstring

[hide private]
[frames] | no frames]

# Class ParsedDocstring

source code

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.

Instance Methods | [hide private]

`(ParsedDocstring, list of Field)`

split_fields(self, errors=None) Split this docstring into its body and its fields. | source code call graph

Call Graph

(ParsedDocstring, `bool`)

summary(self) Returns: A pair consisting of a short summary of this docstring and a boolean value indicating whether there is further documentation in addition to the summary. | source code

concatenate(self, other) Returns: A new parsed docstring containing the concatination of this docstring and `other`. | source code call graph

Call Graph

__add__(self, other) | source code call graph

Call Graph

`string`

to_html(self, docstring_linker, **options) Translate this docstring to HTML. | source code call graph

Call Graph

`string`

to_latex(self, docstring_linker, **options) Translate this docstring to LaTeX. | source code

`string`

to_plaintext(self, docstring_linker, **options) Translate this docstring to plaintext. | source code

`list` of `ParsedDocstring`

index_terms(self) Returns: The list of index terms that are defined in this docstring. | source code call graph

Call Graph

Method Details | [hide private]

### split_fields(self, errors=None)

source code
call graph

Call Graph

Split this docstring into its body and its fields.

Parameters:
  - `errors` (`list` of ParseError) - A list where any errors generated during splitting will be stored. If no list is specified, then errors will be ignored.
Returns: `(ParsedDocstring, list of Field)`
  A tuple `(body, fields)`, where `body` is the main body of this docstring, and `fields` is a list of its fields. If the resulting body is empty, return `None` for the body.

### summary(self)

source code

Returns: (ParsedDocstring, `bool`)
  A pair consisting of a short summary of this docstring and a boolean value indicating whether there is further documentation in addition to the summary. Typically, the summary consists of the first sentence of the docstring.

### concatenate(self, other)

source code
call graph

Call Graph

Returns:
  A new parsed docstring containing the concatination of this docstring and `other`.
Raises:
  - `ValueError` - If the two parsed docstrings are incompatible.

### to_html(self, docstring_linker, **options)

source code
call graph

Call Graph

Translate this docstring to HTML.

Parameters:
  - `docstring_linker` (DocstringLinker) - An HTML translator for crossreference links into and out of the docstring.
  - `options` - Any extra options for the output. Unknown options are ignored.
Returns: `string`
  An HTML fragment that encodes this docstring.

### to_latex(self, docstring_linker, **options)

source code

Translate this docstring to LaTeX.

Parameters:
  - `docstring_linker` (DocstringLinker) - A LaTeX translator for crossreference links into and out of the docstring.
  - `options` - Any extra options for the output. Unknown options are ignored.
Returns: `string`
  A LaTeX fragment that encodes this docstring.

### to_plaintext(self, docstring_linker, **options)

source code

Translate this docstring to plaintext.

Parameters:
  - `docstring_linker` (DocstringLinker) - A plaintext translator for crossreference links into and out of the docstring.
  - `options` - Any extra options for the output. Unknown options are ignored.
Returns: `string`
  A plaintext fragment that encodes this docstring.

### index_terms(self)

source code
call graph

Call Graph

Returns: `list` of `ParsedDocstring`
  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.