Package epydoc :: Package markup :: Class ParsedDocstring

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

__add__(self, other)

concatenate(self, other)

list of ParsedDocstring index_terms(self)

(ParsedDocstring, list of Field) split_fields(self, errors=None)
Split this docstring into its body and its fields.

ParsedDocstring summary(self)

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	[hide private]

add(self, other)
(Addition operator)

source code

concatenate(self, other)

source code

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)

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.

split_fields(self, errors=None)

source code

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.

summary(self)

source code

Returns: ParsedDocstring: A short summary of this docstring. Typically, the summary consists of the first sentence of the docstring.

to_html(self, docstring_linker, **options)

source code

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.

Class ParsedDocstring source code

Subclassing

__add__(self, other) (Addition operator)

concatenate(self, other)

index_terms(self)

split_fields(self, errors=None)

summary(self)

to_html(self, docstring_linker, **options)

to_latex(self, docstring_linker, **options)

to_plaintext(self, docstring_linker, **options)

Class ParsedDocstring
source code

add(self, other)
(Addition operator)