epydoc.objdoc.ObjDoc

Package epydoc :: Module objdoc :: Class ObjDoc

[show private | hide private]

Class ObjDoc

Known Subclasses:: ClassDoc, FuncDoc, ModuleDoc, PropertyDoc

A base class for encoding the information about a Python object that is necessary to create its documentation. This base class defines the following pieces of documentation:

uid: The object's unique identifier.
descr: A full description of the object.
summary: A summary description of the object.
fields: A list of generic docstring fields, such as authors, version, and notes. The list of standard generic docstring fields is defined by the variable ObjDoc.STANDARD_FIELDS; but the user may also add new generic docstring fields (via @newfield or __extra_epydoc_fields__).
sortorder: The object's sort order, as defined by the @sort field.
groups: Groupings for contained objects (or parameters).

Method Summary
	`__init__(self, uid, verbosity, docstring)` Create the documentation for the given object.
	`__include(self, docstring)`
	`_sort(self, items)` Return a copy of the list `items`, sorted first by `sortorder`, and then by name.
Accessors
`UID`	`uid(self)` Return the UID of the object documented by this `ObjDoc`.
`markup.ParsedDocstring`	`descr(self)` Return a description of the object documented by this `ObjDoc`.
`list` of `DocField`	`fields(self)` Return a list of the fields that are given values in the docstring of the object documented by this `ObjDoc`.
`list` of `markup.ParsedDocstring`	`field_values(self, field)` Return a list of the values that are specified for the given field in the docstring of the object documented by this `ObjDoc`.
`list` of `string`	`sortorder(self)` Return a list specifying the sort order that should be used for the object's children.
`list` of `string`	`groups(self)` Return a list of the names of the groups that are defined for the object documented by this `ObjDoc`.
`list` of `(string, elt)`	`by_group(self, elts)` Divide a set of elements into groups.
`boolean`	`has_docstring(self)` Return true if the object documented by this `ObjDoc` has a docstring.
`markup.ParsedDocstring`	`summary(self)` Return a summary of the description of the object documented by this `ObjDoc`.
`boolean`	`defines_groups(self)` Return true if the object documented by this `ObjDoc` defines any groups.
Error Handling
`None`	`_print_errors(self, stream)` Print any errors that were encountered while constructing this `ObjDoc` to `stream`.
Docstring Parsing
	`__parse_docstring(self, docstring)`
	`_process_field(self, tag, arg, descr, warnings)` Process a field from this object's docstring.

Instance Variable Summary
`UID`	`_uid`: The object's unique identifier
Error Handling
	`_parse_warnings`: Warnings generated when parsing the object's docstring.
	`_parse_errors`: Errors generated when parsing the object's docstring.
	`_field_warnings`: Warnings generated when processing the object's docstring's fields.
	`_misc_warnings`: Warnings that are not related to the object's docstring.
Docstring Parsing
`markup.ParsedDocstring`	`_descr`: The object's description, encoded as epytext.
`dictionary` from `DocField` to `list` of `markup.ParsedDocstring`	`_fields`: Documentation fields that were extracted from the object's docstring.

Class Variable Summary
Docstring Parsing
`List` of `DocField`	`STANDARD_FIELDS`: The list of standard docstring fields that epydoc accepts.

Method Details

uid(self)

Returns:: The UID of the object documented by this ObjDoc.
(type=UID)

descr(self)

Returns:: A description of the object documented by this ObjDoc.
(type=markup.ParsedDocstring)

fields(self)

Returns:: A list of the fields that are given values in the docstring of the object documented by this ObjDoc. The fields are listed in the order that they first appear in the docstring.
(type=list of DocField)

field_values(self, field)

Returns:: A list of the values that are specified for the given field in the docstring of the object documented by this ObjDoc. Values are listed in the order that they appear in the docstring.
(type=list of markup.ParsedDocstring)

sortorder(self)

Returns:: A list specifying the sort order that should be used for the object's children. Elements that are in this list should appear before elements that are not in this list; and elements that are in this list should appear in the order that they appear in this list.
(type=list of string)

groups(self)

Returns:: A list of the names of the groups that are defined for the object documented by this ObjDoc. To divide a set of children into groups, use by_group.
(type=list of string)

by_group(self, elts)

Divide a set of elements into groups. Typical usage:

>>> grouped_funcs = fdoc.by_group(fdoc.functions())
>>> for (group, members) in grouped_funcs:
...     print group, members

Parameters:: elts - The set of elements that should be divided into groups. These elements should be Links, Vars, or Params specifying child objects of the object documented by this ObjDoc.
(type=list of (Link or Var or ObjDoc))

Returns:: A list of tuples of the form (name, members), where name is the name of a group; and members is a list of the elements in elts that are in the group. Group membership is tested with the elt.name() method, so every element in elts must define that method.
(type=list of (string, elt))

has_docstring(self)

Returns:: True if the object documented by this ObjDoc has a docstring.
(type=boolean)

summary(self)

Returns:: A summary of the description of the object documented by this ObjDoc.
(type=markup.ParsedDocstring)

defines_groups(self)

Returns:: True if the object documented by this ObjDoc defines any groups.
(type=boolean)

_print_errors(self, stream=None)

Print any errors that were encountered while constructing this ObjDoc to stream. This method should be called at the end of the constructor of every class that is derived from ObjDoc (after the base ObjDoc constructor has been called).

Returns:: None

_process_field(self, tag, arg, descr, warnings)

Process a field from this object's docstring. ObjDoc._process_field be overridden by child classes of ObjDoc, and called as the default case.

Parameters:: tag - The field's tag name
(type=string); arg - The field's optional argument (or None if no argument was specified).
(type=string); descr - The field's body.
(type=markup.ParsedDocstring); warnings - A list of warnings that have been encountered. If any new warnings are encountered, then they should be appended to this list.

init(self, uid, verbosity=0, docstring=None)
(Constructor)

Create the documentation for the given object.

Parameters:: uid - The UID of the object to document.
(type=UID); verbosity - The verbosity of output produced when creating documentation for the object. More positive numbers produce more verbose output; negative numbers supress warnings and errors.
(type=int)

_sort(self, items)

Parameters:: items
(type=list of (UID or Link or Var))

Returns:

A copy of the list items, sorted first by sortorder, and then by name. Item names are sorted as follows:

'__init__' < anything else
public < private
otherwise, alphabetically (case isensitive).

Instance Variable Details

_parse_warnings

Warnings generated when parsing the object's docstring.

_parse_errors

Errors generated when parsing the object's docstring.

_field_warnings

Warnings generated when processing the object's docstring's fields.

_misc_warnings

Warnings that are not related to the object's docstring.

_descr

The object's description, encoded as epytext.

Type:: markup.ParsedDocstring

_fields

Documentation fields that were extracted from the object's docstring. The list of fields that are accepted by epydoc is defined by STANDARD_FIELDS.

Type:: dictionary from DocField to list of markup.ParsedDocstring

_uid

The object's unique identifier

Type:: UID

Class Variable Details

STANDARD_FIELDS

The list of standard docstring fields that epydoc accepts. The order of fields is significant: when the fields are rendered, they will be listed in the order that they are given in this list. Note that this list does not include special fields, such as "group"; it just includes "simple" fields, which contain a single textual description or a list of textual descriptions.

Type:: List of DocField
Value:: [<Field: depreciated>, <Field: version>, <Field: date>, <Field: status>, <Field: author>, <Field: contact>, <Field: organization>, <Field: copyright>, ...

Generated by Epydoc 2.1 on Sat Mar 20 17:46:17 2004

http://epydoc.sf.net