epydoc.docbuilder

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',
      ...