Package epydoc :: Package markup :: Class ParsedDocstring

Class ParsedDocstring

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.

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

(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

__add__(self, other)

source code
call graph

string

to_html(self, docstring_linker, **options)
Translate this docstring to HTML.

source code
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

Method Details

[hide private]

split_fields(self, errors=None)

source code
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

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

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

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.