Package markup
source code
Markup language support for docstrings. Each submodule defines a
parser for a single markup language. These parsers convert an object's
docstring to a ParsedDocstring, a standard intermediate representation
that can be used to generate output. ParsedDocstring
s
support the following operations:
The parse()
function provides a single interface to the epydoc.markup
package: it takes a docstring and the name of a markup language;
delegates to the appropriate parser; and returns the parsed docstring
(along with any errors or warnings that were generated).
The ParsedDocstring
output generation methods
(to_format()
) use a DocstringLinker to link the docstring output with the
rest of the documentation that epydoc generates.
DocstringLinker
s are currently responsible for translating
two kinds of crossreference:
A parsed docstring's fields can be extracted using the ParsedDocstring.split_fields() method. This method
divides a docstring into its main body and a list of Fields, each of
which encodes a single field. The field's bodies are encoded as
ParsedDocstring
s.
Markup errors are represented using ParseErrors.
These exception classes record information about the cause, location, and
severity of each error.
ParsedDocstring
A standard intermediate representation for parsed docstrings that
can be used to generate output.
|
Field
The contents of a docstring's field.
|
DocstringLinker
A translator for crossreference links into and out of a
ParsedDocstring .
|
ConcatenatedDocstring
|
ParseError
The base class for errors generated while parsing docstrings.
|
|
Call Graph |
Parse the given docstring, and use it to construct a
ParsedDocstring . If any fatal ParseError s are
encountered while parsing the docstring, then the docstring will be
rendered as plaintext, instead.
- Parameters:
docstring (string ) - The docstring to encode.
markup (string ) - The name of the markup language that is used by the docstring.
If the markup language is not supported, then the docstring will
be treated as plaintext. The markup name is case-insensitive.
errors (list of ParseError) - A list where any errors generated during parsing will be stored.
If no list is specified, then fatal errors will generate
exceptions, and non-fatal errors will be ignored.
- Returns: ParsedDocstring
- A ParsedDocstring that encodes the contents of
docstring .
- Raises:
ParseError - If errors is None and an error is
encountered while parsing.
|
register_markup_language(name,
parse_function)
| source code
|
Register a new markup language named name , which can be
parsed by the function parse_function .
- Parameters:
|
Print a warning message. If the given error has already been printed,
then do nothing.
|
- Parameters:
obj (any) - The object whose type should be returned as DOM document.
- Returns: ParsedDocstring
- A
ParsedDocstring that encodes the type of the given
object.
|
_markup_language_registry
- Value:
{'restructuredtext': 'epydoc.markup.restructuredtext', 'epytext': 'epy
doc.markup.epytext', 'plaintext': 'epydoc.markup.plaintext', 'javadoc'
: 'epydoc.markup.javadoc',}
|
|
MARKUP_LANGUAGES_USED
- Value:
set([ ' epytext ' , ' plaintext ' , u' restructuredtext ' ])
|
|