Package epydoc :: Module docbuilder

[hide private]
[frames] | no frames]

# Module docbuilder

source code

Construct data structures that encode the API documentation for Python objects. These data structures are created using a series of steps:

1. Building docs: Extract basic information about the objects, and objects that are related to them. This can be done by introspecting the objects' values (with epydoc.docintrospecter; or by parsing their source code (with epydoc.docparser.
2. Merging: Combine the information obtained from introspection & parsing each object into a single structure.
3. Linking: Replace any 'pointers' that were created for imported variables by their target (if it's available).
4. Naming: Chose a unique 'canonical name' for each object.
5. Docstring Parsing: Parse the docstring of each object, and extract any pertinant information.
6. Inheritance: Add information about variables that classes inherit from their base classes.

The documentation information for each individual object is represented using an APIDoc; and the documentation for a collection of objects is represented using a DocIndex.

The main interface to `epydoc.docbuilder` consists of two functions:

- build_doc() -- Builds documentation for a single item, and returns it as an APIDoc object.
- build_doc_index() -- Builds documentation for a collection of items, and returns it as a DocIndex object.

The remaining functions are used by these two main functions to perform individual steps in the creation of the documentation.

Classes | [hide private]

| BuildOptions Holds the parameters for a documentation building process.
| _ProgressEstimator Used to keep track of progress when generating the initial docs for the given items.

Functions | [hide private]

_report_errors(name, introspect_doc, parse_doc, introspect_error, parse_error) | source code call graph

Call Graph

find_overrides(class_doc) Set the `overrides` attribute for all variables in `class_doc`. | source code call graph

Call Graph

Documentation Construction

APIDoc

build_doc(item, introspect=True, parse=True, add_submodules=True, exclude_introspect=None, exclude_parse=None) Build API documentation for a given item, and return it as an APIDoc object. | source code

DocIndex

build_doc_index(items, introspect=True, parse=True, add_submodules=True, exclude_introspect=None, exclude_parse=None) Build API documentation for the given list of items, and return it in the form of a DocIndex. | source code call graph

Call Graph

_report_valdoc_progress(i, val_doc, val_docs) | source code call graph

Call Graph

_get_docs_from_items(items, options) | source code call graph

Call Graph

_get_docs_from_pyobject(obj, options, progress_estimator) | source code

_get_docs_from_pyname(name, options, progress_estimator, suppress_warnings=False) | source code

_get_docs_from_pyscript(filename, options, progress_estimator) | source code

_get_docs_from_module_file(filename, options, progress_estimator, parent_docs=`(`None`,` None`)`) Construct and return the API documentation for the python module with the given filename. | source code call graph

Call Graph

_get_docs_from_submodules(item, pkg_docs, options, progress_estimator) | source code call graph

Call Graph

Merging

register_attribute_mergefunc(attrib, mergefunc) Register an attribute merge function. | source code

merge_docs(introspect_doc, parse_doc, cyclecheck=None, path=None) Merge the API documentation information that was obtained from introspection with information that was obtained from parsing. | source code call graph

Call Graph

_merge_posargs_and_defaults(introspect_doc, parse_doc, path) | source code call graph

Call Graph

merge_attribute(attrib, introspect_doc, parse_doc, cyclecheck, path) | source code call graph

Call Graph

merge_variables(varlist1, varlist2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_value(value1, value2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_overrides(v1, v2, precedence, cyclecheck, path) | source code

merge_fget(v1, v2, precedence, cyclecheck, path) | source code

merge_fset(v1, v2, precedence, cyclecheck, path) | source code

merge_fdel(v1, v2, precedence, cyclecheck, path) | source code

merge_proxy_for(v1, v2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_bases(baselist1, baselist2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_posarg_defaults(defaults1, defaults2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_docstring(docstring1, docstring2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_docs_extracted_by(v1, v2, precedence, cyclecheck, path) | source code call graph

Call Graph

merge_submodules(v1, v2, precedence, cyclecheck, path) | source code call graph

Call Graph

Linking

link_imports(val_doc, docindex) | source code call graph

Call Graph

Naming

assign_canonical_names(val_doc, name, docindex, score=0) Assign a canonical name to `val_doc` (if it doesn't have one already), and (recursively) to each variable in `val_doc`. | source code call graph

Call Graph

_var_shadows_self(var_doc, varname) | source code call graph

Call Graph

_fix_self_shadowing_var(var_doc, varname, docindex) | source code

_unreachable_name_for(val_doc, docindex) | source code call graph

Call Graph

Inheritance

inherit_docs(class_doc) | source code call graph

Call Graph

_inherit_info(var_doc) Copy any relevant documentation information from the variable that `var_doc` overrides into `var_doc` itself. | source code call graph

Call Graph

Variables | [hide private]

| _INHERITED_ATTRIBS = ``[``'``descr``'``,` `'``summary``'``,` `'``metadata``'``,` `'``extra_d``...``
Merging
| MERGE_PRECEDENCE = ``{``'``canonical_name``'``:` `'``introspect``'``,` `'``docformat``...`` Indicates whether information from introspection or parsing should be given precedence, for specific attributes.
| DEFAULT_MERGE_PRECEDENCE = ``'``introspect``'`` Indicates whether information from introspection or parsing should be given precedence.
| _attribute_mergefunc_registry = `{}`
Naming
| _name_scores = ``{`<GenericValueDoc ??-12>`:` -10000`,` <ModuleDoc Co`...`` A dictionary mapping from each `ValueDoc` to the score that has been assigned to its current cannonical name.
| _unreachable_names = ``{`DottedName('??')`:` 14`,` DottedName('??', '`...`` The set of names that have been used for unreachable objects.

Function Details | [hide private]

### build_doc(item, introspect=True, parse=True, add_submodules=True, exclude_introspect=None, exclude_parse=None)

source code

Build API documentation for a given item, and return it as an APIDoc object.

Parameters:
  - `item` - The item to document, specified using any of the following:
    - A string, naming a python package directory (e.g., `'epydoc/markup'`)
    - A string, naming a python file (e.g., `'epydoc/docparser.py'`)
    - A string, naming a python object (e.g., `'epydoc.docparser.DocParser'`)
    - Any (non-string) python object (e.g., `list.append`)
  - `introspect` - If true, then use introspection to examine the specified items. Otherwise, just use parsing.
  - `parse` - If true, then use parsing to examine the specified items. Otherwise, just use introspection.
Returns: APIDoc

### build_doc_index(items, introspect=True, parse=True, add_submodules=True, exclude_introspect=None, exclude_parse=None)

source code
call graph

Call Graph

Build API documentation for the given list of items, and return it in the form of a DocIndex.

Parameters:
  - `items` - The items to document, specified using any of the following:
    - A string, naming a python package directory (e.g., `'epydoc/markup'`)
    - A string, naming a python file (e.g., `'epydoc/docparser.py'`)
    - A string, naming a python object (e.g., `'epydoc.docparser.DocParser'`)
    - Any (non-string) python object (e.g., `list.append`)
  - `introspect` - If true, then use introspection to examine the specified items. Otherwise, just use parsing.
  - `parse` - If true, then use parsing to examine the specified items. Otherwise, just use introspection.
Returns: DocIndex

### _get_docs_from_module_file(filename, options, progress_estimator, parent_docs=`(`None`,` None`)`)

source code
call graph

Call Graph

Construct and return the API documentation for the python module with the given filename.

Parameters:
  - `parent_docs` - The `ModuleDoc` of the containing package. If `parent_docs` is not provided, then this method will check if the given filename is contained in a package; and if so, it will construct a stub `ModuleDoc` for the containing package(s). `parent_docs` is a tuple, where the first element is the parent from introspection, and the second element is the parent from parsing.

### register_attribute_mergefunc(attrib, mergefunc)

source code

Register an attribute merge function. This function will be called by merge_docs() when it needs to merge the attribute values of two `APIDoc`s.

Parameters:
  - `attrib` - The name of the attribute whose values are merged by `mergefunc`.
  - `mergefunc` - The merge function, whose sinature is:

        >>> def mergefunc(introspect_val, parse_val, precedence, cyclecheck, path):
        ...     return calculate_merged_value(introspect_val, parse_val)

    Where `introspect_val` and `parse_val` are the two values to combine; `precedence` is a string indicating which value takes precedence for this attribute (`'introspect'` or `'parse'`); `cyclecheck` is a value used by `merge_docs()` to make sure that it only visits each pair of docs once; and `path` is a string describing the path that was taken from the root to this attribute (used to generate log messages).

    If the merge function needs to call `merge_docs`, then it should pass `cyclecheck` and `path` back in. (When appropriate, a suffix should be added to `path` to describe the path taken to the merged values.)

### merge_docs(introspect_doc, parse_doc, cyclecheck=None, path=None)

source code
call graph

Call Graph

Merge the API documentation information that was obtained from introspection with information that was obtained from parsing. `introspect_doc` and `parse_doc` should be two `APIDoc` instances that describe the same object. `merge_docs` combines the information from these two instances, and returns the merged `APIDoc`.

If `introspect_doc` and `parse_doc` are compatible, then they will be merged -- i.e., they will be coerced to a common class, and their state will be stored in a shared dictionary. Once they have been merged, any change made to the attributes of one will affect the other. The value for the each of the merged `APIDoc`'s attributes is formed by combining the values of the source `APIDoc`s' attributes, as follows:

- If either of the source attributes' value is `UNKNOWN`, then use the other source attribute's value.
- Otherwise, if an attribute merge function has been registered for the attribute, then use that function to calculate the merged value from the two source attribute values.
- Otherwise, if MERGE_PRECEDENCE is defined for the attribute, then use the attribute value from the source that it indicates.
- Otherwise, use the attribute value from the source indicated by DEFAULT_MERGE_PRECEDENCE.

If `introspect_doc` and `parse_doc` are not compatible (e.g., if their values have incompatible types), then `merge_docs()` will simply return either `introspect_doc` or `parse_doc`, depending on the value of DEFAULT_MERGE_PRECEDENCE. The two input `APIDoc`s will not be merged or modified in any way.

Parameters:
  - `cyclecheck`, `path` - These arguments should only be provided when `merge_docs()` is called by an attribute merge function. See register_attribute_mergefunc() for more details.

### assign_canonical_names(val_doc, name, docindex, score=0)

source code
call graph

Call Graph

Assign a canonical name to `val_doc` (if it doesn't have one already), and (recursively) to each variable in `val_doc`. In particular, `val_doc` will be assigned the canonical name `name` iff either:

- `val_doc`'s canonical name is `UNKNOWN`; or
- `val_doc`'s current canonical name was assigned by this method; but the score of the new name (`score`) is higher than the score of the current name (`score_dict[val_doc]`).

Note that canonical names will even be assigned to values like integers and `None`; but these should be harmless.

### find_overrides(class_doc)

source code
call graph

Call Graph

Set the `overrides` attribute for all variables in `class_doc`. This needs to be done early (before docstring parsing), so we can know which docstrings to suppress warnings for.

Variables Details | [hide private]

### MERGE_PRECEDENCE

Indicates whether information from introspection or parsing should be given precedence, for specific attributes. This dictionary maps from attribute names to either `'introspect'` or `'parse'`.

Value:

      {'canonical_name': 'introspect',
       'docformat': 'parse',
       'docstring': 'introspect',
       'filename': 'parse',
       'is_alias': 'parse',
       'is_imported': 'introspect',
       'is_package': 'parse',
       'repr': 'parse',
      ...

### DEFAULT_MERGE_PRECEDENCE

Indicates whether information from introspection or parsing should be given precedence. Should be either `'introspect'` or `'parse'`

Value:

      'introspect'

### _name_scores

A dictionary mapping from each `ValueDoc` to the score that has been assigned to its current cannonical name. If assign_canonical_names() finds a canonical name with a better score, then it will replace the old name.

Value:

      {<GenericValueDoc ??-12>: -10000,
       <ModuleDoc ConfigParser>: 2147483647,
       <ValueDoc Tkinter.At>: 2147483647,
       <ValueDoc Tkinter.AtEnd>: 2147483647,
       <ValueDoc Tkinter.AtInsert>: 2147483647,
       <ValueDoc Tkinter.AtSelFirst>: 2147483647,
       <ValueDoc Tkinter.AtSelLast>: 2147483647,
       <ValueDoc Tkinter.BaseWidget>: 2147483647,
      ...

### _unreachable_names

The set of names that have been used for unreachable objects. This is used to ensure there are no duplicate cannonical names assigned. `_unreachable_names` is a dictionary mapping from dotted names to integer ids, where the next unused unreachable name derived from dotted name `n` is `DottedName('%s-%s' % (n, str(_unreachable_names[n]+1))`

Value:

      {DottedName('??'): 14,
       DottedName('??', 'APIDoc'): 4,
       DottedName('??', 'ApiLinkReader'): 2,
       DottedName('??', 'ArithmeticError'): 4,
       DottedName('??', 'AssertionError'): 1,
       DottedName('??', 'AttributeError'): 1,
       DottedName('??', 'Body'): 1,
       DottedName('??', 'ClassDoc'): 1,
      ...

### _INHERITED_ATTRIBS

Value:

      ['descr',
       'summary',
       'metadata',
       'extra_docstring_fields',
       'type_descr',
       'arg_descrs',
       'arg_types',
       'return_descr',
      ...