epydoc.objdoc

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

## Module epydoc.objdoc

Support for `ObjDoc`s, which encode the information about a Python object that is necessary to create its documentation. `ObjDoc`s are created and managed by the `DocMap` class, which acts like a dictionary from `UID`s to `ObjDoc`s.

Textual documentation entries (e.g., module descriptions, method descriptions, variable types, see-also entries) are encoded as `ParsedDocstrings`.

Each Python object is identified by a globally unique identifier, implemented with the `UID` class. These identifiers are also used by the `Link` class to implement crossreferencing between `ObjDoc`s.

Classes
`ClassDoc` | The documentation for a class.
`DocField` | A generic docstring field.
`DocMap` | A dictionary mapping each object to the object's documentation.
`FuncDoc` | The documentation for a function.
`ModuleDoc` | The documentation for a module or package.
`ObjDoc` | A base class for encoding the information about a Python object that is necessary to create its documentation.
`Param` | The documentation for a function parameter.
`PropertyDoc` | The documentation for a property.
`Raise` | The documentation for the raising of an exception.
`Var` | The documentation for a variable.

Function Summary
| `report_param_mismatches(docmap)`
`None` | ``set_default_docformat`(new_format)` Change the default value for `__docformat__` to the given value.
| ``_ast_match`(pattern, data, vars, indent)` Match `data` to `pattern`, with variable extraction.
| `_descr_to_docfield(arg, descr)`
`list` of `string` | ``_descr_to_identifiers`(descr)` Given a `ParsedDocstring` that contains a list of identifiers, return a list of those identifiers.
| `_dfs_bases(cls)`
`list` of `class` | ``_find_base_order`(cls)` Return a list of the base ancestors of `cls`, in the order that they should be searched for attributes.
`(string, int)` or `(None, None)` | ``_find_docstring`(uid)` Return the file name and line number of the docstring for the given object; or `None` if the docstring cannot be found.
| ``_flatten`(tree)` Recursively explore `tree`, and return an in-order list of all leaves.
| ``_getdoc`(obj)` Get the documentation string for an object.
| ``_lookup_class_field`(cls, field, base_order)` Find the value for a class's field by looking through its base order list, and using getattr to access the first base that contains the field.

Variable Summary
`str` | `DEFAULT_DOCFORMAT`: The default value for `__docformat__`, if it is not specified by modules.
`tuple` | `KNOWN_DOCFORMATS` = `('plaintext', 'epytext', 'restructure...`
`SRE_Pattern` | `_IDENTIFIER_LIST_REGEXP` = `^[\w\.\*]+([\s,:;]\s*[\w\.\*]+...`
`tuple` | `_KNOWN_FIELD_TAGS` = `('var', 'variable', 'ivar', 'ivariab...`

Function Details

### set_default_docformat(new_format) Change the default value for `__docformat__` to the given value. The current default value for `__docformat__` is recorded in `DEFAULT_DOCFORMAT`. Parameters: `new_format` - The new default value for `__docformat__` (type=`string`) Returns: `None` See Also: `DEFAULT_DOCFORMAT`

### _ast_match(pattern, data, vars=None, indent=0) Match `data` to `pattern`, with variable extraction. The `pattern` value may contain variables of the form `['varname']` which are allowed to match anything. The value that is matched is returned as part of a dictionary which maps 'varname' to the matched value. 'varname' is not required to be a string object, but using strings makes patterns and the code which uses them more readable. Parameters: `pattern` - Pattern to match against, possibly containing variables. `data` - Data to be checked and against which variables are extracted. `vars` - Dictionary of variables which have already been found. If not provided, an empty dictionary is created. Returns: two values -- a boolean indicating whether a match was found and a dictionary mapping variable names to their associated values.

### _descr_to_identifiers(descr) Given a `ParsedDocstring` that contains a list of identifiers, return a list of those identifiers. This is used by fields such as `@group` and `@sort`, which expect lists of identifiers as their values. To extract the identifiers, the docstring is first converted to plaintext, and then split. The plaintext content of the docstring must be a a list of identifiers, separated by spaces, commas, colons, or semicolons. Parameters: `descr` - A `ParsedDocstring` containing a list of identifiers. (type=`markup.ParsedDocstring`) Returns: A list of the identifier names contained in `descr`. (type=`list` of `string`) Raises: `ValueError` - If `descr` does not contain a valid list of identifiers.

### _find_base_order(cls) Returns: A list of the base ancestors of `cls`, in the order that they should be searched for attributes. Each base ancestor should be listed exactly once. The base order list includes the given class as its first element. (type=`list` of `class`)

### _find_docstring(uid) Returns: The file name and line number of the docstring for the given object; or `None` if the docstring cannot be found. Line numbers are indexed from zero (i.e., the first line's line number is 0). (type=`(string, int)` or `(None, None)`)

### _flatten(tree) Recursively explore `tree`, and return an in-order list of all leaves. Parameters: `tree` - The tree whose leaves should be returned. The tree structure of `tree` is represented by tuples and lists. In particular, every tuple or list contained in `tree` is considered a subtree; and any other element is considered a leaf. (type=`list` or `tuple`) Returns: An in-order list of the leaves of `tree`.

### _getdoc(obj) Get the documentation string for an object. This function is similar to `inspect.getdoc`. In particular, it finds the minimum indentation fromthe second line onwards, and removes that indentation from each line. But it also checks to make sure that the docstring is actually a string (since some programs put other data in the docstrings). Parameters: `obj` - The object whose documentation string should be returned. (type=any)

### _lookup_class_field(cls, field, base_order=None) Find the value for a class's field by looking through its base order list, and using getattr to access the first base that contains the field. Note that this is different from just using `getattr` directly, since for methods it will return a method of the base class, rather than a method of the given class. This is useful for constructing UIDs for class methods. Returns: A pair `(val, container)`, where `val` is the value that was found; and `container` is the base that contains `val`.

Variable Details

### DEFAULT_DOCFORMAT The default value for `__docformat__`, if it is not specified by modules. `__docformat__` is a module variable that specifies the markup language for the docstrings in a module. Its value is a string, consisting the name of a markup language, optionally followed by a language code (such as `en` for English). Some typical values for `__docformat__` are:
    >>> __docformat__ = 'plaintext'
    >>> __docformat__ = 'epytext'
    >>> __docformat__ = 'epytext en'
    Type: `str` Value:
        'plaintext'

    ### KNOWN_DOCFORMATS Type: `tuple` Value:
        ('plaintext', 'epytext', 'restructuredtext', 'javadoc')

    ### _IDENTIFIER_LIST_REGEXP Type: `SRE_Pattern` Value:
        ^[\w\.\*]+([\s,:;]\s*[\w\.\*]+)*$

    ### _KNOWN_FIELD_TAGS Type: `tuple` Value:
        ('var',
         'variable',
         'ivar',
         'ivariable',
         'cvar',
         'cvariable',
         'type',
         'group',
        ...

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