Home       Trees       Indices       Help   
epydoc 3.0.1
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]
  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 
 
find_overrides(class_doc)
Set the overrides attribute for all variables in class_doc.		 source code
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 
 
_report_valdoc_progress(i, val_doc, val_docs) source code
call graph 
 
_get_docs_from_items(items, options) source code
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 
 
_get_docs_from_submodules(item, pkg_docs, options, progress_estimator) source code
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 
 
_merge_posargs_and_defaults(introspect_doc, parse_doc, path) source code
call graph 
 
merge_attribute(attrib, introspect_doc, parse_doc, cyclecheck, path) source code
call graph 
 
merge_variables(varlist1, varlist2, precedence, cyclecheck, path) source code
call graph 
 
merge_value(value1, value2, precedence, cyclecheck, path) source code
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 
 
merge_bases(baselist1, baselist2, precedence, cyclecheck, path) source code
call graph 
 
merge_posarg_defaults(defaults1, defaults2, precedence, cyclecheck, path) source code
call graph 
 
merge_docstring(docstring1, docstring2, precedence, cyclecheck, path) source code
call graph 
 
merge_docs_extracted_by(v1, v2, precedence, cyclecheck, path) source code
call graph 
 
merge_submodules(v1, v2, precedence, cyclecheck, path) source code
call graph 
    Linking
 
link_imports(val_doc, docindex) source code
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 
 
_var_shadows_self(var_doc, varname) source code
call graph 
 
_fix_self_shadowing_var(var_doc, varname, docindex) source code
 
_unreachable_name_for(val_doc, docindex) source code
call graph 
    Inheritance
 
inherit_docs(class_doc) source code
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 
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 

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 

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

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 

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.

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

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

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

   Home       Trees       Indices       Help   
epydoc 3.0.1
Generated by Epydoc 3.0.1 on Wed Jan 30 14:06:01 2008 http://epydoc.sourceforge.net