Package epydoc :: Package markup

[hide private]
[frames] | no frames]

# 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:

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

Submodules | [hide private]

- epydoc.markup.doctest: Syntax highlighting for doctest blocks.
- epydoc.markup.epytext: Parser for epytext strings.
- epydoc.markup.javadoc: Epydoc parser for Javadoc docstrings.
- epydoc.markup.plaintext: Parser for plaintext docstrings.
- epydoc.markup.pyval_repr: Syntax highlighter for Python values.
- epydoc.markup.restructuredtext: Epydoc parser for ReStructuredText strings.

Classes | [hide private]

| 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
Errors and Warnings
| ParseError The base class for errors generated while parsing docstrings.

Functions | [hide private]

ParsedDocstring

parse(docstring, markup=`'``plaintext``'`, errors=None, **options) Parse the given docstring, and use it to construct a `ParsedDocstring`. | source code call graph

Call Graph

register_markup_language(name, parse_function) Register a new markup language named `name`, which can be parsed by the function `parse_function`. | source code

_parse_warn(estr) Print a warning message. | source code

Utility Functions

ParsedDocstring

parse_type_of(obj) Returns: A `ParsedDocstring` that encodes the type of the given object. | source code

Variables | [hide private]

| _markup_language_registry = `{'restructuredtext': 'epydoc.marku`...``
| MARKUP_LANGUAGES_USED = ``set([``'``epytext``'``,` `'``plaintext``'``,` `u'``restruc``...``
| _parse_warnings = ``{``}`` Used by _parse_warn.
`int` | SCRWIDTH The default width with which text will be wrapped when formatting the output of the parser.

Function Details | [hide private]

### parse(docstring, markup=`'``plaintext``'`, errors=None, **options)

source code
call graph

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:
  - `name` - The name of the markup language. `name` should be a simple identifier, such as `'epytext'` or `'restructuredtext'`. Markup language names are case insensitive.
  - `parse_function` - A function which can be used to parse the markup language, and returns a ParsedDocstring. It should have the following signature:

        >>> def parse(s, errors):
        ...     'returns a ParsedDocstring'

    Where:

    - `s` is the string to parse. (`s` will be a unicode string.)
    - `errors` is a list; any errors that are generated during docstring parsing should be appended to this list (as ParseError objects).

### _parse_warn(estr)

source code

Print a warning message. If the given error has already been printed, then do nothing.

### parse_type_of(obj)

source code

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.

Variables Details | [hide private]

### _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'])