epydoc.epytext

Package	Module	Class	Trees	Index	Help

epydoc

[show private | hide private]

Module epydoc.epytext

Parser for epytext strings. Epytext is a lightweight markup whose primary intended application is Python documentation strings. This parser converts Epytext strings to a XML/DOM representation. Epytext strings can contain the following structural blocks:

epytext: The top-level element of the DOM tree.
para: A paragraph of text. Paragraphs contain no newlines, and all spaces are soft.
section: A section or subsection.
field: A tagged field. These fields provide information about specific aspects of a Python object, such as the description of a function's parameter, or the author of a module.
literalblock: A block of literal text. This text should be displayed as it would be displayed in plaintext. The parser removes the appropriate amount of leading whitespace from each line in the literal block.
doctestblock: A block containing sample python code, formatted according to the specifications of the doctest module.
ulist: An unordered list.
olist: An ordered list.
li: A list item. This tag is used both for unordered list items and for ordered list items.

Additionally, the following inline regions may be used within para blocks:

code: Source code and identifiers.
math: Mathematical expressions.
index: A term which should be included in an index, if one is generated.
italic: Italicized text.
bold: Bold-faced text.
uri: A Universal Resource Indicator (URI) or Universal Resource Locator (URL)
link: A Python identifier which should be hyperlinked to the named object's documentation, when possible.

The returned DOM tree will confirm to the the following Document Type Description:

  <!ENTITY % colorized '(code | math | index | italic |
                         bold | uri | link)*'>

  <!ELEMENT epytext ((para | literalblock | doctestblock |
                     section | ulist | olist)*, fieldlist?)>

  <!ELEMENT para (#PCDATA | %colorized;)*>

  <!ELEMENT section (para | listblock | doctestblock |
                     section | ulist | olist)+>

  <!ELEMENT fieldlist (field+)>
  <!ELEMENT field (tag, (para | listblock | doctestblock)
                         ulist | olist)+)>
  <!ELEMENT tag (#PCDATA)>
  
  <!ELEMENT literalblock (#PCDATA)>
  <!ELEMENT doctestblock (#PCDATA)>

  <!ELEMENT ulist (li+)>
  <!ELEMENT olist (li+)>
  <!ELEMENT li (para | literalblock | doctestblock | ulist | olist)+>
  <!ATTLIST li bullet NMTOKEN #IMPLIED>
  <!ATTLIST olist start NMTOKEN #IMPLIED>

  <!ELEMENT uri    (name, target)>
  <!ELEMENT link   (name, target)>
  <!ELEMENT name   (#PCDATA | %colorized;)*>
  <!ELEMENT target (#PCDATA)>
  
  <!ELEMENT code   (#PCDATA | %colorized;)*>
  <!ELEMENT math   (#PCDATA | %colorized;)*>
  <!ELEMENT italic (#PCDATA | %colorized;)*>
  <!ELEMENT bold   (#PCDATA | %colorized;)*>
  <!ELEMENT index  (#PCDATA | %colorized;)>

Classes
*`Token`*	`Token`s are an intermediate data structure used while constructing the structuring DOM tree for a formatted docstring.

Exceptions
*`ColorizingError`*	A warning or error generated while colorizing a paragraph.
*`ParseError`*	The base class for warnings and errors generated while parsing epytext strings.
*`StructuringError`*	A warning or error generated while structuring a formatted documentation string.
*`TokenizationError`*	A warning or error generated while tokenizing a formatted documentation string.

Function Summary
`xml.dom.minidom.Element`	`parse(str, errors, warnings)` Return a DOM tree encoding the contents of an epytext string.
`xml.dom.minidom.Element`	`parse_as_literal(str)` Return a DOM tree matching the epytext DTD, containing a single literal block.
`xml.dom.minidom.Element`	`pparse(str, show_warnings, show_errors)` Pretty-parse the string.
`xml.dom.minidom.Element`	`summary(tree)` Given a DOM tree representing formatted documentation, return a new DOM tree containing the documentation's first sentence.
`string`	`to_debug(tree, indent, seclevel)` Convert a DOM tree encoding epytext back to an epytext string, annotated with extra debugging information.
`string`	`to_epytext(tree, indent, seclevel)` Convert a DOM tree encoding epytext back to an epytext string.
`string`	`to_plaintext(tree, indent, seclevel)` Convert a DOM tree encoding epytext to a string representation.
`string`	`wordwrap(str, indent, right)` Word-wrap the given string.

Variable Summary
`int`	`SCRWIDTH` - The default width with which text will be wrapped when formatting the output of the parser.

Function Details

parse

parse(str, errors=None, warnings=None)

Return a DOM tree encoding the contents of an epytext string. Any errors or warnings generated during parsing will be stored in the errors and warnings parameters.

Parameters:: str - The epytext string to parse.
(type=string); errors - A list where any errors generated during parsing will be stored. If no list is specified, then errors will generate exceptions.
(type=list of ParseError); warnings - A list where any warnings generated during parsing will be stored. If no list is specified, then warnings will be silently ignored.
(type=list of ParseError)

Returns:: a DOM tree encoding the contents of an epytext string.
(type=xml.dom.minidom.Element)

Raises:: ParseError - If errors is None and an error is encountered while parsing.

parse_as_literal

parse_as_literal(str)

Return a DOM tree matching the epytext DTD, containing a single literal block. That literal block will include the contents of the given string. This method is typically used as a fall-back when the parser fails.

Parameters:: str - The string which should be enclosed in a literal block.
(type=string)

Returns:: A DOM tree containing str in a single literal block.
(type=xml.dom.minidom.Element)

pparse

pparse(str, show_warnings=1, show_errors=1)

Pretty-parse the string. This parses the string, and catches any warnings or errors produced. Any warnings and errors are displayed, and the resulting DOM parse structure is returned.

Parameters:: str - The string to parse.
(type=string); show_warnings - Whether or not to display warnings generated by parsing str.
(type=boolean); show_errors - Whether or not to display errors generated by parsing str.
(type=boolean)

Returns:: a DOM tree encoding the contents of str.
(type=xml.dom.minidom.Element)

Raises:: SyntaxError - If any fatal errors were encountered.

summary

summary(tree)

Given a DOM tree representing formatted documentation, return a new DOM tree containing the documentation's first sentence.

Parameters:: tree - A DOM tree representing formatted documentation, as produced by parse.
(type=xml.dom.minidom.Element)

Returns:: A DOM tree containing the first sentence of the documentation.
(type=xml.dom.minidom.Element)

to_debug

to_debug(tree, indent=4, seclevel=0)

Convert a DOM tree encoding epytext back to an epytext string, annotated with extra debugging information. This function is similar to to_epytext, but it adds explicit information about where different blocks begin, along the left margin.

Parameters:: tree - A DOM tree encoding of an epytext string.
(type=xml.dom.minidom.Element); indent - The indentation for the string representation of tree. Each line of the returned string will begin with indent space characters.
(type=int); seclevel - The section level that tree appears at. This is used to generate section headings.
(type=int)

Returns:: The epytext string corresponding to tree.
(type=string)

to_epytext

to_epytext(tree, indent=0, seclevel=0)

Convert a DOM tree encoding epytext back to an epytext string. This is the inverse operation from parse. I.e., assuming there are no errors, the following is true:

parse(to_epytext(tree)) == tree

The inverse is true, except that whitespace, line wrapping, and character escaping may be done differently.

to_epytext(parse(str)) == str (approximately)

Parameters:: tree - A DOM tree encoding of an epytext string.
(type=xml.dom.minidom.Element); indent - The indentation for the string representation of tree. Each line of the returned string will begin with indent space characters.
(type=int); seclevel - The section level that tree appears at. This is used to generate section headings.
(type=int)

Returns:: The epytext string corresponding to tree.
(type=string)

to_plaintext

to_plaintext(tree, indent=0, seclevel=0)

Convert a DOM tree encoding epytext to a string representation. This representation is similar to the string generated by to_epytext, but to_plaintext removes inline markup, prints escaped characters in unescaped form, etc.

Parameters:: tree - A DOM tree encoding of an epytext string.
(type=xml.dom.minidom.Element); indent - The indentation for the string representation of tree. Each line of the returned string will begin with indent space characters.
(type=int); seclevel - The section level that tree appears at. This is used to generate section headings.
(type=int)

Returns:: The epytext string corresponding to tree.
(type=string)

wordwrap

wordwrap(str, indent=0, right=75)

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)

Returns:: A word-wrapped version of str.
(type=string)

Variable Details

SCRWIDTH

The default width with which text will be wrapped when formatting the output of the parser.

Type: int

Package	Module	Class	Trees	Index	Help

epydoc

Generated by Epydoc on Sun Oct 6 03:32:11 2002

http://epydoc.sf.net