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). ParsedDocstrings 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