epydoc.markup

Package epydoc :: Package markup |
[show private | hide private]
[frames | no frames]

## Package epydoc.markup

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:

- output generation (`to_plaintext()`, `to_html()`, and `to_latex()`).
- Summarization (`summary()`).
- Field extraction (`split_fields()`).
- Index term extraction (`index_terms()`.

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:

- index terms (`translate_indexterm()`).
- identifier crossreferences (`translate_identifier_xref()`).

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 `Field`s, each of which encodes a single field. The field's bodies are encoded as `ParsedDocstring`s.

Markup errors are represented using `ParseError`s. These exception classes record information about the cause, location, and severity of each error.

The `epydoc.markup` module also defines several utility functions, such as `wordwrap`, `plaintext_to_latex`, and `plaintext_to_html`, which are used by several different markup language parsers.

Submodules
`epytext`: Parser for epytext strings. `javadoc`: Epydoc parser for Javadoc docstrings. `plaintext`: Parser for plaintext docstrings. `restructuredtext`: Epydoc parser for ReStructuredText strings.

Classes
`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`.

Exceptions
Errors and Warnings
`ParseError` | The base class for errors generated while parsing docstrings.

Function Summary
`ParsedDocstring` | ``parse`(docstring, markup, errors, **options)` Parse the given docstring, and use it to construct a `ParsedDocstring`.
`string` | ``plaintext_to_html`(str)` Return an HTML string that encodes the given plaintext string.
| ``_parse_warn`(estr)` Print a warning message.
Utility Functions
`string` | ``wordwrap`(str, indent, right, startindex)` Word-wrap the given string.
`string` | ``plaintext_to_latex`(str, nbsp, breakany)` Return a LaTeX string that encodes the given plaintext string.
`ParsedDocstring` | ``parse_type_of`(obj)` Return a `ParsedDocstring` that encodes the type of the given object.

Variable Summary
`int` | `SCRWIDTH`: The default width with which text will be wrapped when formatting the output of the parser.
`dict` | `_parse_warnings`: Used by `_parse_warn`.

Function Details

### parse(docstring, markup='plaintext', errors=None, **options) 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` - The docstring to encode. (type=`string`) `markup` - 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. (type=`string`) `errors` - 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. (type=`list` of `ParseError`) Returns: A `ParsedDocstring` that encodes the contents of `docstring`. (type=`ParsedDocstring`) Raises: `ParseError` - If `errors` is `None` and an error is encountered while parsing.

### wordwrap(str, indent=0, right=73, startindex=0) Word-wrap the given string. All sequences of whitespace are converted into spaces, and the string is broken up into lines, where each line begins with `indent` spaces, followed by one or more (space-deliniated) words whose length is less than `right-indent`. If a word is longer than `right-indent` characters, then it is put on its own line. Parameters: `str` - The string that should be word-wrapped. (type=`int`) `indent` - The left margin of the string. `indent` spaces will be inserted at the beginning of every line. (type=`int`) `right` - The right margin of the string. (type=`int`) `startindex` - The index at which the first line starts. This is useful if you want to include other contents on the first line. (type=`int`) Returns: A word-wrapped version of `str`. (type=`string`)

### plaintext_to_latex(str, nbsp=0, breakany=0) Parameters: `nbsp` - Replace every space with a non-breaking space (`'~'`). `breakany` - Insert hyphenation marks, so that LaTeX can break the resulting string at any point. This is useful for small boxes (e.g., the type box in the variable list table). Returns: A LaTeX string that encodes the given plaintext string. In particular, special characters (such as `'$'` and `'_'`) are escaped, and tabs are expanded. (type=`string`)

### parse_type_of(obj) Parameters: `obj` - The object whose type should be returned as DOM document. (type=any) Returns: A `ParsedDocstring` that encodes the type of the given object. (type=`ParsedDocstring`)

### plaintext_to_html(str) Returns: An HTML string that encodes the given plaintext string. In particular, special characters (such as `'<'` and `'&'`) are escaped. (type=`string`)

### _parse_warn(estr) Print a warning message. If the given error has already been printed, then do nothing.

Variable Details

    ### SCRWIDTH The default width with which text will be wrapped when formatting the output of the parser. Type: `int` Value:
        73

    ### _parse_warnings Used by `_parse_warn`. Type: `dict` Value:
        {}

Generated by Epydoc 2.1 on Sat Mar 20 17:46:17 2004 | http://epydoc.sf.net