Module docbuilder

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

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

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

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.

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.

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.

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'