Home       Trees       Index       Help   

epydoc 3.0alpha2

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: The remaining functions are used by these two main functions to perform individual steps in the creation of the documentation.

Classes [hide private]
_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)
    Documentation Construction
APIDoc build_doc(item, introspect=True, parse=True, add_submodules=True)
Build API documentation for a given item, and return it as an APIDoc object.
DocIndex build_doc_index(items, introspect=True, parse=True, add_submodules=True)
Build API documentation for the given list of items, and return it in the form of a DocIndex.
  _report_valdoc_progress(i, val_doc, val_docs)
  _get_docs_from_items(items, introspect, parse, add_submodules)
  _get_docs_from_pyobject(obj, introspect, parse, progress_estimator)
  _get_docs_from_pyname(name, introspect, parse, progress_estimator, supress_warnings=False)
  _get_docs_from_pyscript(filename, introspect, parse, progress_estimator)
  _get_docs_from_module_file(filename, introspect, parse, progress_estimator, parent_docs=(None,None))
Construct and return the API documentation for the python module with the given filename.
  _get_docs_from_submodules(item, pkg_docs, introspect, parse, progress_estimator)
    Merging
  register_attribute_mergefunc(attrib, mergefunc)
Register an attribute merge function.
  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.
  _merge_posargs_and_defaults(introspect_doc, parse_doc, path)
  merge_attribute(attrib, introspect_doc, parse_doc, cyclecheck, path)
  merge_variables(varlist1, varlist2, precedence, cyclecheck, path)
  merge_value(value1, value2, precedence, cyclecheck, path)
  merge_package(v1, v2, precedence, cyclecheck, path)
  merge_container(v1, v2, precedence, cyclecheck, path)
  merge_overrides(v1, v2, precedence, cyclecheck, path)
  merge_fget(v1, v2, precedence, cyclecheck, path)
  merge_fset(v1, v2, precedence, cyclecheck, path)
  merge_fdel(v1, v2, precedence, cyclecheck, path)
  merge_proxy_for(v1, v2, precedence, cyclecheck, path)
  merge_bases(baselist1, baselist2, precedence, cyclecheck, path)
  merge_posarg_defaults(defaults1, defaults2, precedence, cyclecheck, path)
  merge_docstring(docstring1, docstring2, precedence, cyclecheck, path)
  merge_docs_extracted_by(v1, v2, precedence, cyclecheck, path)
    Linking
  link_imports(val_doc, docindex)
    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.
  _var_shadows_self(var_doc, varname)
  _fix_self_shadowing_var(var_doc, varname, docindex)
  _unreachable_name_for(val_doc, docindex)
    Inheritance
  inherit_docs(class_doc)
  _inherit_info(var_doc)
Copy any relevant documentation information from the variable that var_doc overrides into var_doc itself.

Variables [hide private]
_INHERITED_ATTRIBS  
    Merging
MERGE_PRECEDENCE Indicates whether information from introspection or parsing should be given precedence, for specific attributes.
DEFAULT_MERGE_PRECEDENCE Indicates whether information from introspection or parsing should be given precedence.
_attribute_mergefunc_registry  
    Naming
_name_scores A dictionary mapping from each ValueDoc to the score that has been assigned to its current cannonical name.
_unreachable_names 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)

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)

source code 
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

_report_valdoc_progress(i, val_doc, val_docs)

source code 
call graph 

_get_docs_from_items(items, introspect, parse, add_submodules)

source code 
call graph 

_get_docs_from_pyobject(obj, introspect, parse, progress_estimator)

source code 

_get_docs_from_pyname(name, introspect, parse, progress_estimator, supress_warnings=False)

source code 

_get_docs_from_pyscript(filename, introspect, parse, progress_estimator)

source code 

_get_docs_from_module_file(filename, introspect, parse, progress_estimator, parent_docs=(None,None))

source code 
Construct and return the API documentation for the python module with the given filename.
Parameters:
  • parent_doc - The ModuleDoc of the containing package. If parent_doc 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).

_get_docs_from_submodules(item, pkg_docs, introspect, parse, progress_estimator)

source code 

_report_errors(name, introspect_doc, parse_doc, introspect_error, parse_error)

source code 

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 APIDocs.
Parameters:
  • attrib - The name of the attribute whose values are merged by mergefunc.
  • mergefun - 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 

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

_merge_posargs_and_defaults(introspect_doc, parse_doc, path)

source code 

merge_attribute(attrib, introspect_doc, parse_doc, cyclecheck, path)

source code 

merge_variables(varlist1, varlist2, precedence, cyclecheck, path)

source code 

merge_value(value1, value2, precedence, cyclecheck, path)

source code 

merge_package(v1, v2, precedence, cyclecheck, path)

source code 

merge_container(v1, v2, precedence, cyclecheck, path)

source code 

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 

merge_bases(baselist1, baselist2, precedence, cyclecheck, path)

source code 

merge_posarg_defaults(defaults1, defaults2, precedence, cyclecheck, path)

source code 

merge_docstring(docstring1, docstring2, precedence, cyclecheck, path)

source code 

merge_docs_extracted_by(v1, v2, precedence, cyclecheck, path)

source code 

link_imports(val_doc, docindex)

source code 

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

source code 
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.

_var_shadows_self(var_doc, varname)

source code 

_fix_self_shadowing_var(var_doc, varname, docindex)

source code 

_unreachable_name_for(val_doc, docindex)

source code 

inherit_docs(class_doc)

source code 

_inherit_info(var_doc)

source code 
Copy any relevant documentation information from the variable that var_doc overrides into var_doc itself.

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': 'parse',
 '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'

_attribute_mergefunc_registry

Value:
{'bases': <function merge_bases at 0x402583ac>,
 'docs_extracted_by': <function merge_docs_extracted_by at 0x40258454>\
,
 'docstring': <function merge_docstring at 0x4025841c>,
 'fdel': <function merge_fdel at 0x4025833c>,
 'fget': <function merge_fget at 0x402582cc>,
 'fset': <function merge_fset at 0x40258304>,
 'overrides': <function merge_overrides at 0x40258294>,
...

_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:
{<ValueDoc Tkinter.BaseWidget>: 2147483647,
 <RoutineDoc __builtin__.unichr>: -11,
 <ModuleDoc epydoc.docwriter.html>: 2147483647,
 <RoutineDoc epydoc.docwriter.plaintext.PlaintextWriter.write_function\
>: 2147483647,
 <RoutineDoc list.__getslice__>: -21,
 <RoutineDoc list.__reversed__>: -21,
 <GenericValueDoc type.__weakrefoffset__>: -21,
...

_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.
Value:
set([DottedName('??-45'), DottedName('??', 'Childless-5'), DottedName(\
'??', 'epydoc', 'docwriter-6'), DottedName('??-31'), DottedName('??', \
'complex'), DottedName('??', 'Notation'), DottedName('??-29'), DottedN\
ame('??', 'epydoc', 'docintrospecter'), DottedName('??', 'GetattrMagic\
-3'), DottedName('??-6'), DottedName('??', 'EnvironmentError'), Dotted\
Name('??', 'epydoc', 'markup-4'), DottedName('??', 'NamedNodeMap'), Do\
ttedName('??-42'), DottedName('??', 'NoModificationAllowedErr'), Dotte\
dName('??-38'), DottedName('??', 'ParseError-7'), DottedName('??-22'),\
...

_INHERITED_ATTRIBS

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

   Home       Trees       Index       Help   

epydoc 3.0alpha2

Generated by Epydoc 3.0alpha2 on Tue Apr 11 17:29:56 2006 http://epydoc.sf.net