epydoc.objdoc.ObjDoc

Package epydoc :: Module objdoc :: Class ObjDoc |
[show private | hide private]
[frames | no frames]

## 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 `Link`s, `Var`s, or `Param`s 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