bee_python 0.0.3 → 0.0.4

data/tools/epydoc/apidoc.py

@@ -1,2203 +0,0 @@
-# epydoc -- API Documentation Classes
-#
-# Copyright (C) 2005 Edward Loper
-# Author: Edward Loper <edloper@loper.org>
-# URL: <http://epydoc.sf.net>
-#
-# $Id: apidoc.py,v 1.1 2009/11/26 13:20:35 casa Exp $
-
-"""
-Classes for encoding API documentation about Python programs.
-These classes are used as a common representation for combining
-information derived from introspection and from parsing.
-
-The API documentation for a Python program is encoded using a graph of
-L{APIDoc} objects, each of which encodes information about a single
-Python variable or value.  C{APIDoc} has two direct subclasses:
-L{VariableDoc}, for documenting variables; and L{ValueDoc}, for
-documenting values.  The C{ValueDoc} class is subclassed further, to
-define the different pieces of information that should be recorded
-about each value type:
-
-G{classtree: APIDoc}
-
-The distinction between variables and values is intentionally made
-explicit.  This allows us to distinguish information about a variable
-itself (such as whether it should be considered 'public' in its
-containing namespace) from information about the value it contains
-(such as what type the value has).  This distinction is also important
-because several variables can contain the same value: each variable
-should be described by a separate C{VariableDoc}; but we only need one
-C{ValueDoc}, since they share a single value.
-
-@todo: Add a cache to canonical name lookup?
-"""
-__docformat__ = 'epytext en'
-
-######################################################################
-## Imports
-######################################################################
-
-import types, re, os.path, pickle
-from epydoc import log
-import epydoc
-import __builtin__
-from epydoc.compat import * # Backwards compatibility
-from epydoc.util import decode_with_backslashreplace, py_src_filename
-import epydoc.markup.pyval_repr
-
-######################################################################
-# Dotted Names
-######################################################################
-
-class DottedName:
-    """
-    A sequence of identifiers, separated by periods, used to name a
-    Python variable, value, or argument.  The identifiers that make up
-    a dotted name can be accessed using the indexing operator:
-
-        >>> name = DottedName('epydoc', 'api_doc', 'DottedName')
-        >>> print name
-        epydoc.apidoc.DottedName
-        >>> name[1]
-        'api_doc'
-    """
-    UNREACHABLE = "??"
-    _IDENTIFIER_RE = re.compile("""(?x)
-        (%s |             # UNREACHABLE marker, or..
-         (script-)?       #   Prefix: script (not a module)
-         \w+              #   Identifier (yes, identifiers starting with a
-                          #   digit are allowed. See SF bug #1649347)
-         '?)              #   Suffix: submodule that is shadowed by a var
-        (-\d+)?           # Suffix: unreachable vals with the same name
-        $"""
-        % re.escape(UNREACHABLE))
-
-    class InvalidDottedName(ValueError):
-        """
-        An exception raised by the DottedName constructor when one of
-        its arguments is not a valid dotted name.
-        """
-
-    _ok_identifiers = set()
-    """A cache of identifier strings that have been checked against
-    _IDENTIFIER_RE and found to be acceptable."""
-    
-    def __init__(self, *pieces, **options):
-        """
-        Construct a new dotted name from the given sequence of pieces,
-        each of which can be either a C{string} or a C{DottedName}.
-        Each piece is divided into a sequence of identifiers, and
-        these sequences are combined together (in order) to form the
-        identifier sequence for the new C{DottedName}.  If a piece
-        contains a string, then it is divided into substrings by
-        splitting on periods, and each substring is checked to see if
-        it is a valid identifier.
-
-        As an optimization, C{pieces} may also contain a single tuple
-        of values.  In that case, that tuple will be used as the
-        C{DottedName}'s identifiers; it will I{not} be checked to
-        see if it's valid.
-
-        @kwparam strict: if true, then raise an L{InvalidDottedName}
-        if the given name is invalid.
-        """
-        if len(pieces) == 1 and isinstance(pieces[0], tuple):
-            self._identifiers = pieces[0] # Optimization
-            return
-        if len(pieces) == 0:
-            raise DottedName.InvalidDottedName('Empty DottedName')
-        self._identifiers = []
-        for piece in pieces:
-            if isinstance(piece, DottedName):
-                self._identifiers += piece._identifiers
-            elif isinstance(piece, basestring):
-                for subpiece in piece.split('.'):
-                    if piece not in self._ok_identifiers:
-                        if not self._IDENTIFIER_RE.match(subpiece):
-                            if options.get('strict'):
-                                raise DottedName.InvalidDottedName(
-                                    'Bad identifier %r' % (piece,))
-                            else:
-                                log.warning("Identifier %r looks suspicious; "
-                                            "using it anyway." % piece)
-                        self._ok_identifiers.add(piece)
-                    self._identifiers.append(subpiece)
-            else:
-                raise TypeError('Bad identifier %r: expected '
-                                'DottedName or str' % (piece,))
-        self._identifiers = tuple(self._identifiers)
-
-    def __repr__(self):
-        idents = [`ident` for ident in self._identifiers]
-        return 'DottedName(' + ', '.join(idents) + ')'
-
-    def __str__(self):
-        """
-        Return the dotted name as a string formed by joining its
-        identifiers with periods:
-
-            >>> print DottedName('epydoc', 'api_doc', DottedName')
-            epydoc.apidoc.DottedName
-        """
-        return '.'.join(self._identifiers)
-
-    def __add__(self, other):
-        """
-        Return a new C{DottedName} whose identifier sequence is formed
-        by adding C{other}'s identifier sequence to C{self}'s.
-        """
-        if isinstance(other, (basestring, DottedName)):
-            return DottedName(self, other)
-        else:
-            return DottedName(self, *other)
-
-    def __radd__(self, other):
-        """
-        Return a new C{DottedName} whose identifier sequence is formed
-        by adding C{self}'s identifier sequence to C{other}'s.
-        """
-        if isinstance(other, (basestring, DottedName)):
-            return DottedName(other, self)
-        else:
-            return DottedName(*(list(other)+[self]))
-
-    def __getitem__(self, i):
-        """
-        Return the C{i}th identifier in this C{DottedName}.  If C{i} is
-        a non-empty slice, then return a C{DottedName} built from the
-        identifiers selected by the slice.  If C{i} is an empty slice,
-        return an empty list (since empty C{DottedName}s are not valid).
-        """
-        if isinstance(i, types.SliceType):
-            pieces = self._identifiers[i.start:i.stop]
-            if pieces: return DottedName(pieces)
-            else: return []
-        else:
-            return self._identifiers[i]
-
-    def __hash__(self):
-        return hash(self._identifiers)
-
-    def __cmp__(self, other):
-        """
-        Compare this dotted name to C{other}.  Two dotted names are
-        considered equal if their identifier subsequences are equal.
-        Ordering between dotted names is lexicographic, in order of
-        identifier from left to right.
-        """
-        if not isinstance(other, DottedName):
-            return -1
-        return cmp(self._identifiers, other._identifiers)
-
-    def __len__(self):
-        """
-        Return the number of identifiers in this dotted name.
-        """
-        return len(self._identifiers)
-
-    def container(self):
-        """
-        Return the DottedName formed by removing the last identifier
-        from this dotted name's identifier sequence.  If this dotted
-        name only has one name in its identifier sequence, return
-        C{None} instead.
-        """
-        if len(self._identifiers) == 1:
-            return None
-        else:
-            return DottedName(*self._identifiers[:-1])
-
-    def dominates(self, name, strict=False):
-        """
-        Return true if this dotted name is equal to a prefix of
-        C{name}.  If C{strict} is true, then also require that
-        C{self!=name}.
-
-            >>> DottedName('a.b').dominates(DottedName('a.b.c.d'))
-            True
-        """
-        len_self = len(self._identifiers)
-        len_name = len(name._identifiers)
-
-        if (len_self > len_name) or (strict and len_self == len_name):
-            return False
-        # The following is redundant (the first clause is implied by
-        # the second), but is done as an optimization.
-        return ((self._identifiers[0] == name._identifiers[0]) and
-                self._identifiers == name._identifiers[:len_self])
-
-    def contextualize(self, context):
-        """
-        If C{self} and C{context} share a common ancestor, then return
-        a name for C{self}, relative to that ancestor.  If they do not
-        share a common ancestor (or if C{context} is C{UNKNOWN}), then
-        simply return C{self}.
-
-        This is used to generate shorter versions of dotted names in
-        cases where users can infer the intended target from the
-        context.
-        
-        @type context: L{DottedName}
-        @rtype: L{DottedName}
-        """
-        if context is UNKNOWN or not context or len(self) <= 1:
-            return self
-        if self[0] == context[0]:
-            return self[1:].contextualize(context[1:])
-        else:
-            return self
-
-        # Find the first index where self & context differ.
-        for i in range(min(len(context), len(self))):
-            if self._identifiers[i] != context._identifiers[i]:
-                first_difference = i
-                break
-        else:
-            first_difference = i+1
-            
-        # Strip off anything before that index.
-        if first_difference == 0:
-            return self
-        elif first_difference == len(self):
-            return self[-1:]
-        else:
-            return self[first_difference:]
-
-######################################################################
-# UNKNOWN Value
-######################################################################
-
-class _Sentinel:
-    """
-    A unique value that won't compare equal to any other value.  This
-    class is used to create L{UNKNOWN}.
-    """
-    def __init__(self, name):
-        self.name = name
-    def __repr__(self):
-        return '<%s>' % self.name
-    def __nonzero__(self):
-        raise ValueError('Sentinel value <%s> can not be used as a boolean' %
-                         self.name)
-
-UNKNOWN = _Sentinel('UNKNOWN')
-"""A special value used to indicate that a given piece of
-information about an object is unknown.  This is used as the
-default value for all instance variables."""
-
-######################################################################
-# API Documentation Objects: Abstract Base Classes
-######################################################################
-
-class APIDoc(object):
-    """
-    API documentation information for a single element of a Python
-    program.  C{APIDoc} itself is an abstract base class; subclasses
-    are used to specify what information should be recorded about each
-    type of program element.  In particular, C{APIDoc} has two direct
-    subclasses, C{VariableDoc} for documenting variables and
-    C{ValueDoc} for documenting values; and the C{ValueDoc} class is
-    subclassed further for different value types.
-
-    Each C{APIDoc} subclass specifies the set of attributes that
-    should be used to record information about the corresponding
-    program element type.  The default value for each attribute is
-    stored in the class; these default values can then be overridden
-    with instance variables.  Most attributes use the special value
-    L{UNKNOWN} as their default value, to indicate that the correct
-    value for that attribute has not yet been determined.  This makes
-    it easier to merge two C{APIDoc} objects that are documenting the
-    same element (in particular, to merge information about an element
-    that was derived from parsing with information that was derived
-    from introspection).
-
-    For all attributes with boolean values, use only the constants
-    C{True} and C{False} to designate true and false.  In particular,
-    do I{not} use other values that evaluate as true or false, such as
-    C{2} or C{()}.  This restriction makes it easier to handle
-    C{UNKNOWN} values.  For example, to test if a boolean attribute is
-    C{True} or C{UNKNOWN}, use 'C{attrib in (True, UNKNOWN)}' or
-    'C{attrib is not False}'.
-
-    Two C{APIDoc} objects describing the same object can be X{merged},
-    using the method L{merge_and_overwrite(other)}.  After two
-    C{APIDoc}s are merged, any changes to one will be reflected in the
-    other.  This is accomplished by setting the two C{APIDoc} objects
-    to use a shared instance dictionary.  See the documentation for
-    L{merge_and_overwrite} for more information, and some important
-    caveats about hashing.
-    """
-    #{ Docstrings
-    docstring = UNKNOWN
-    """@ivar: The documented item's docstring.
-       @type: C{string} or C{None}"""
-    
-    docstring_lineno = UNKNOWN
-    """@ivar: The line number on which the documented item's docstring
-       begins.
-       @type: C{int}"""
-    #} end of "docstrings" group
-
-    #{ Information Extracted from Docstrings
-    descr = UNKNOWN
-    """@ivar: A description of the documented item, extracted from its
-       docstring.
-       @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
-    
-    summary = UNKNOWN
-    """@ivar: A summary description of the documented item, extracted from
-       its docstring.
-       @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
-    
-    other_docs = UNKNOWN
-    """@ivar: A flag indicating if the entire L{docstring} body (except tags
-       if any) is entirely included in the L{summary}.
-       @type: C{bool}"""
-    
-    metadata = UNKNOWN
-    """@ivar: Metadata about the documented item, extracted from fields in
-       its docstring.  I{Currently} this is encoded as a list of tuples
-       C{(field, arg, descr)}.  But that may change.
-       @type: C{(str, str, L{ParsedDocstring<markup.ParsedDocstring>})}"""
-    
-    extra_docstring_fields = UNKNOWN
-    """@ivar: A list of new docstring fields tags that are defined by the
-       documented item's docstring.  These new field tags can be used by
-       this item or by any item it contains.
-       @type: L{DocstringField <epydoc.docstringparser.DocstringField>}"""
-    #} end of "information extracted from docstrings" group
-
-    #{ Source Information
-    docs_extracted_by = UNKNOWN # 'parser' or 'introspecter' or 'both'
-    """@ivar: Information about where the information contained by this
-       C{APIDoc} came from.  Can be one of C{'parser'},
-       C{'introspector'}, or C{'both'}.
-       @type: C{str}"""
-    #} end of "source information" group
-
-    def __init__(self, **kwargs):
-        """
-        Construct a new C{APIDoc} object.  Keyword arguments may be
-        used to initialize the new C{APIDoc}'s attributes.
-        
-        @raise TypeError: If a keyword argument is specified that does
-            not correspond to a valid attribute for this (sub)class of
-            C{APIDoc}.
-        """
-        if epydoc.DEBUG:
-            for key in kwargs:
-                if key[0] != '_' and not hasattr(self.__class__, key):
-                    raise TypeError('%s got unexpected arg %r' %
-                                    (self.__class__.__name__, key))
-        self.__dict__.update(kwargs)
-
-    def _debug_setattr(self, attr, val):
-        """
-        Modify an C{APIDoc}'s attribute.  This is used when
-        L{epydoc.DEBUG} is true, to make sure we don't accidentally
-        set any inappropriate attributes on C{APIDoc} objects.
-
-        @raise AttributeError: If C{attr} is not a valid attribute for
-            this (sub)class of C{APIDoc}.  (C{attr} is considered a
-            valid attribute iff C{self.__class__} defines an attribute
-            with that name.)
-        """
-        # Don't intercept special assignments like __class__, or
-        # assignments to private variables.
-        if attr.startswith('_'):
-            return object.__setattr__(self, attr, val)
-        if not hasattr(self, attr):
-            raise AttributeError('%s does not define attribute %r' %
-                            (self.__class__.__name__, attr))
-        self.__dict__[attr] = val
-
-    if epydoc.DEBUG:
-        __setattr__ = _debug_setattr
-
-    def __repr__(self):
-       return '<%s>' % self.__class__.__name__
-    
-    def pp(self, doublespace=0, depth=5, exclude=(), include=()):
-        """
-        Return a pretty-printed string representation for the
-        information contained in this C{APIDoc}.
-        """
-        return pp_apidoc(self, doublespace, depth, exclude, include)
-    __str__ = pp
-
-    def specialize_to(self, cls):
-        """
-        Change C{self}'s class to C{cls}.  C{cls} must be a subclass
-        of C{self}'s current class.  For example, if a generic
-        C{ValueDoc} was created for a value, and it is determined that
-        the value is a routine, you can update its class with:
-        
-            >>> valdoc.specialize_to(RoutineDoc)
-        """
-        if not issubclass(cls, self.__class__):
-            raise ValueError('Can not specialize to %r' % cls)
-        # Update the class.
-        self.__class__ = cls
-        # Update the class of any other apidoc's in the mergeset.
-        if self.__mergeset is not None:
-            for apidoc in self.__mergeset:
-                apidoc.__class__ = cls
-        # Re-initialize self, in case the subclass constructor does
-        # any special processing on its arguments.
-        self.__init__(**self.__dict__)
-
-    __has_been_hashed = False
-    """True iff L{self.__hash__()} has ever been called."""
-    
-    def __hash__(self):
-        self.__has_been_hashed = True
-        return id(self.__dict__)
-
-    def __cmp__(self, other):
-        if not isinstance(other, APIDoc): return -1
-        if self.__dict__ is other.__dict__: return 0
-        name_cmp = cmp(self.canonical_name, other.canonical_name)
-        if name_cmp == 0: return -1
-        else: return name_cmp
-
-    def is_detailed(self):
-        """
-        Does this object deserve a box with extra details?
-
-        @return: True if the object needs extra details, else False.
-        @rtype: C{bool}
-        """
-        if self.other_docs is True:
-            return True
-
-        if self.metadata is not UNKNOWN:
-            return bool(self.metadata)
-
-    __mergeset = None
-    """The set of all C{APIDoc} objects that have been merged with
-    this C{APIDoc} (using L{merge_and_overwrite()}).  Each C{APIDoc}
-    in this set shares a common instance dictionary (C{__dict__})."""
-    
-    def merge_and_overwrite(self, other, ignore_hash_conflict=False):
-        """
-        Combine C{self} and C{other} into a X{merged object}, such
-        that any changes made to one will affect the other.  Any
-        attributes that C{other} had before merging will be discarded.
-        This is accomplished by copying C{self.__dict__} over
-        C{other.__dict__} and C{self.__class__} over C{other.__class__}.
-
-        Care must be taken with this method, since it modifies the
-        hash value of C{other}.  To help avoid the problems that this
-        can cause, C{merge_and_overwrite} will raise an exception if
-        C{other} has ever been hashed, unless C{ignore_hash_conflict}
-        is True.  Note that adding C{other} to a dictionary, set, or
-        similar data structure will implicitly cause it to be hashed.
-        If you do set C{ignore_hash_conflict} to True, then any
-        existing data structures that rely on C{other}'s hash staying
-        constant may become corrupted.
-
-        @return: C{self}
-        @raise ValueError: If C{other} has ever been hashed.
-        """
-        # If we're already merged, then there's nothing to do.
-        if (self.__dict__ is other.__dict__ and
-            self.__class__ is other.__class__): return self
-            
-        if other.__has_been_hashed and not ignore_hash_conflict:
-            raise ValueError("%r has already been hashed!  Merging it "
-                             "would cause its has value to change." % other)
-
-        # If other was itself already merged with anything,
-        # then we need to merge those too.
-        a,b = (self.__mergeset, other.__mergeset)
-        mergeset = (self.__mergeset or [self]) + (other.__mergeset or [other])
-        other.__dict__.clear()
-        for apidoc in mergeset:
-            #if apidoc is self: pass
-            apidoc.__class__ = self.__class__
-            apidoc.__dict__ = self.__dict__
-        self.__mergeset = mergeset
-        # Sanity chacks.
-        assert self in mergeset and other in mergeset
-        for apidoc in mergeset:
-            assert apidoc.__dict__ is self.__dict__
-        # Return self.
-        return self
-
-    def apidoc_links(self, **filters):
-        """
-        Return a list of all C{APIDoc}s that are directly linked from
-        this C{APIDoc} (i.e., are contained or pointed to by one or
-        more of this C{APIDoc}'s attributes.)
-
-        Keyword argument C{filters} can be used to selectively exclude
-        certain categories of attribute value.  For example, using
-        C{includes=False} will exclude variables that were imported
-        from other modules; and C{subclasses=False} will exclude
-        subclasses.  The filter categories currently supported by
-        epydoc are:
-          - C{imports}: Imported variables.
-          - C{packages}: Containing packages for modules.
-          - C{submodules}: Contained submodules for packages.
-          - C{bases}: Bases for classes.
-          - C{subclasses}: Subclasses for classes.
-          - C{variables}: All variables.
-          - C{private}: Private variables.
-          - C{overrides}: Points from class variables to the variables
-            they override.  This filter is False by default.
-        """
-        return []
-
-def reachable_valdocs(root, **filters):
-    """
-    Return a list of all C{ValueDoc}s that can be reached, directly or
-    indirectly from the given root list of C{ValueDoc}s.
-
-    @param filters: A set of filters that can be used to prevent
-        C{reachable_valdocs} from following specific link types when
-        looking for C{ValueDoc}s that can be reached from the root
-        set.  See C{APIDoc.apidoc_links} for a more complete
-        description.
-    """
-    apidoc_queue = list(root)
-    val_set = set()
-    var_set = set()
-    while apidoc_queue:
-        api_doc = apidoc_queue.pop()
-        if isinstance(api_doc, ValueDoc):
-            val_set.add(api_doc)
-        else:
-            var_set.add(api_doc)
-        apidoc_queue.extend([v for v in api_doc.apidoc_links(**filters)
-                             if v not in val_set and v not in var_set])
-    return val_set
-
-######################################################################
-# Variable Documentation Objects
-######################################################################
-
-class VariableDoc(APIDoc):
-    """
-    API documentation information about a single Python variable.
-
-    @note: The only time a C{VariableDoc} will have its own docstring
-    is if that variable was created using an assignment statement, and
-    that assignment statement had a docstring-comment or was followed
-    by a pseudo-docstring.
-    """
-    #{ Basic Variable Information
-    name = UNKNOWN
-    """@ivar: The name of this variable in its containing namespace.
-       @type: C{str}"""
-    
-    container = UNKNOWN
-    """@ivar: API documentation for the namespace that contains this
-       variable.
-       @type: L{ValueDoc}"""
-    
-    canonical_name = UNKNOWN
-    """@ivar: A dotted name that serves as a unique identifier for
-       this C{VariableDoc}.  It should be formed by concatenating
-       the C{VariableDoc}'s C{container} with its C{name}.
-       @type: L{DottedName}"""
-
-    value = UNKNOWN
-    """@ivar: The API documentation for this variable's value.
-       @type: L{ValueDoc}"""
-    #}
-
-    #{ Information Extracted from Docstrings
-    type_descr = UNKNOWN 
-    """@ivar: A description of the variable's expected type, extracted from
-       its docstring.
-       @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
-    #} end of "information extracted from docstrings" group
-    
-    #{ Information about Imported Variables
-    imported_from = UNKNOWN
-    """@ivar: The fully qualified dotted name of the variable that this
-       variable's value was imported from.  This attribute should only
-       be defined if C{is_instvar} is true.
-       @type: L{DottedName}"""
-
-    is_imported = UNKNOWN
-    """@ivar: Was this variable's value imported from another module?
-       (Exception: variables that are explicitly included in __all__ have
-       C{is_imported} set to C{False}, even if they are in fact
-       imported.)
-       @type: C{bool}"""
-    #} end of "information about imported variables" group
-
-    #{ Information about Variables in Classes
-    is_instvar = UNKNOWN
-    """@ivar: If true, then this variable is an instance variable; if false,
-       then this variable is a class variable.  This attribute should
-       only be defined if the containing namespace is a class    
-       @type: C{bool}"""
-    
-    overrides = UNKNOWN # [XXX] rename -- don't use a verb.
-    """@ivar: The API documentation for the variable that is overridden by
-       this variable.  This attribute should only be defined if the
-       containing namespace is a class.
-       @type: L{VariableDoc}"""
-    #} end of "information about variables in classes" group
-
-    #{ Flags
-    is_alias = UNKNOWN
-    """@ivar: Is this variable an alias for another variable with the same
-       value?  If so, then this variable will be dispreferred when
-       assigning canonical names.
-       @type: C{bool}"""
-    
-    is_public = UNKNOWN
-    """@ivar: Is this variable part of its container's public API?
-       @type: C{bool}"""
-    #} end of "flags" group
-
-    def __init__(self, **kwargs):
-        APIDoc.__init__(self, **kwargs)
-        if self.is_public is UNKNOWN and self.name is not UNKNOWN:
-            self.is_public = (not self.name.startswith('_') or
-                              self.name.endswith('_'))
-        
-    def __repr__(self):
-        if self.canonical_name is not UNKNOWN:
-            return '<%s %s>' % (self.__class__.__name__, self.canonical_name)
-        if self.name is not UNKNOWN:
-            return '<%s %s>' % (self.__class__.__name__, self.name)
-        else:                     
-            return '<%s>' % self.__class__.__name__
-
-    def _get_defining_module(self):
-        if self.container is UNKNOWN:
-            return UNKNOWN
-        return self.container.defining_module
-    defining_module = property(_get_defining_module, doc="""
-    A read-only property that can be used to get the variable's
-    defining module.  This is defined as the defining module
-    of the variable's container.""")
-
-    def apidoc_links(self, **filters):
-        # nb: overrides filter is *False* by default.
-        if (filters.get('overrides', False) and
-            (self.overrides not in (None, UNKNOWN))):
-            overrides = [self.overrides]
-        else:
-            overrides = []
-        if self.value in (None, UNKNOWN):
-            return []+overrides
-        else:
-            return [self.value]+overrides
-
-    def is_detailed(self):
-        pval = super(VariableDoc, self).is_detailed()
-        if pval or self.value in (None, UNKNOWN):
-            return pval
-
-        if (self.overrides not in (None, UNKNOWN) and
-            isinstance(self.value, RoutineDoc)):
-            return True
-
-        if isinstance(self.value, GenericValueDoc):
-            # [XX] This is a little hackish -- we assume that the
-            # summary lines will have SUMMARY_REPR_LINELEN chars,
-            # that len(name) of those will be taken up by the name,
-            # and that 3 of those will be taken up by " = " between
-            # the name & val.  Note that if any docwriter uses a
-            # different formula for maxlen for this, then it will
-            # not get the right value for is_detailed().
-            maxlen = self.value.SUMMARY_REPR_LINELEN-3-len(self.name)
-            return (not self.value.summary_pyval_repr(maxlen).is_complete)
-        else:
-            return self.value.is_detailed()
-
-######################################################################
-# Value Documentation Objects
-######################################################################
-
-class ValueDoc(APIDoc):
-    """
-    API documentation information about a single Python value.
-    """
-    canonical_name = UNKNOWN
-    """@ivar: A dotted name that serves as a unique identifier for
-       this C{ValueDoc}'s value.  If the value can be reached using a
-       single sequence of identifiers (given the appropriate imports),
-       then that sequence of identifiers is used as its canonical name.
-       If the value can be reached by multiple sequences of identifiers
-       (i.e., if it has multiple aliases), then one of those sequences of
-       identifiers is used.  If the value cannot be reached by any
-       sequence of identifiers (e.g., if it was used as a base class but
-       then its variable was deleted), then its canonical name will start
-       with C{'??'}.  If necessary, a dash followed by a number will be
-       appended to the end of a non-reachable identifier to make its
-       canonical name unique.
-
-       When possible, canonical names are chosen when new C{ValueDoc}s
-       are created.  However, this is sometimes not possible.  If a
-       canonical name can not be chosen when the C{ValueDoc} is created,
-       then one will be assigned by L{assign_canonical_names()
-       <docbuilder.assign_canonical_names>}.
-       
-       @type: L{DottedName}"""
-
-    #{ Value Representation
-    pyval = UNKNOWN
-    """@ivar: A pointer to the actual Python object described by this
-       C{ValueDoc}.  This is used to display the value (e.g., when
-       describing a variable.)  Use L{pyval_repr()} to generate a
-       plaintext string representation of this value.
-       @type: Python object"""
-
-    parse_repr = UNKNOWN
-    """@ivar: A text representation of this value, extracted from 
-       parsing its source code.  This representation may not accurately
-       reflect the actual value (e.g., if the value was modified after
-       the initial assignment).
-       @type: C{unicode}"""
-
-    REPR_MAXLINES = 5
-    """@cvar: The maximum number of lines of text that should be
-    generated by L{pyval_repr()}.  If the string representation does
-    not fit in this number of lines, an ellpsis marker (...) will
-    be placed at the end of the formatted representation."""
-
-    REPR_LINELEN = 75
-    """@cvar: The maximum number of characters for lines of text that
-    should be generated by L{pyval_repr()}.  Any lines that exceed
-    this number of characters will be line-wrappped; The S{crarr}
-    symbol will be used to indicate that the line was wrapped."""
-
-    SUMMARY_REPR_LINELEN = 75
-    """@cvar: The maximum number of characters for the single-line
-    text representation generated by L{summary_pyval_repr()}.  If
-    the value's representation does not fit in this number of
-    characters, an ellipsis marker (...) will be placed at the end
-    of the formatted representation."""
-
-    REPR_MIN_SCORE = 0
-    """@cvar: The minimum score that a value representation based on
-    L{pyval} should have in order to be used instead of L{parse_repr}
-    as the canonical representation for this C{ValueDoc}'s value.
-    @see: L{epydoc.markup.pyval_repr}"""
-    #} end of "value representation" group
-
-    #{ Context
-    defining_module = UNKNOWN
-    """@ivar: The documentation for the module that defines this
-       value.  This is used, e.g., to lookup the appropriate markup
-       language for docstrings.  For a C{ModuleDoc},
-       C{defining_module} should be C{self}.
-       @type: L{ModuleDoc}"""
-    #} end of "context group"
-
-    #{ Information about Imported Variables
-    proxy_for = None # [xx] in progress.
-    """@ivar: If C{proxy_for} is not None, then this value was
-       imported from another file.  C{proxy_for} is the dotted name of
-       the variable that this value was imported from.  If that
-       variable is documented, then its C{value} may contain more
-       complete API documentation about this value.  The C{proxy_for}
-       attribute is used by the source code parser to link imported
-       values to their source values (in particular, for base
-       classes).  When possible, these proxy C{ValueDoc}s are replaced
-       by the imported value's C{ValueDoc} by
-       L{link_imports()<docbuilder.link_imports>}.
-       @type: L{DottedName}"""
-    #} end of "information about imported variables" group
-
-    #: @ivar:
-    #: This is currently used to extract values from __all__, etc, in
-    #: the docparser module; maybe I should specialize
-    #: process_assignment and extract it there?  Although, for __all__,
-    #: it's not clear where I'd put the value, since I just use it to
-    #: set private/public/imported attribs on other vars (that might not
-    #: exist yet at the time.)
-    toktree = UNKNOWN
-
-    def __repr__(self):
-        if self.canonical_name is not UNKNOWN:
-            return '<%s %s>' % (self.__class__.__name__, self.canonical_name)
-        else:
-            return '<%s %s>' % (self.__class__.__name__,
-                                self.summary_pyval_repr().to_plaintext(None))
-
-    def __setstate__(self, state):
-        self.__dict__ = state
-
-    def __getstate__(self):
-        """
-        State serializer for the pickle module.  This is necessary
-        because sometimes the C{pyval} attribute contains an
-        un-pickleable value.
-        """
-        # Construct our pickled dictionary.  Maintain this dictionary
-        # as a private attribute, so we can reuse it later, since
-        # merged objects need to share a single dictionary.
-        if not hasattr(self, '_ValueDoc__pickle_state'):
-            # Make sure __pyval_repr & __summary_pyval_repr are cached:
-            self.pyval_repr(), self.summary_pyval_repr()
-            # Construct the dictionary; leave out 'pyval'.
-            self.__pickle_state = self.__dict__.copy()
-            self.__pickle_state['pyval'] = UNKNOWN
-
-        if not isinstance(self, GenericValueDoc):
-            assert self.__pickle_state != {}
-        # Return the pickle state.
-        return self.__pickle_state
-
-    #{ Value Representation
-    def pyval_repr(self):
-        """
-        Return a formatted representation of the Python object
-        described by this C{ValueDoc}.  This representation may
-        include data from introspection or parsing, and is authorative
-        as 'the best way to represent a Python value.'  Any lines that
-        go beyond L{REPR_LINELEN} characters will be wrapped; and if
-        the representation as a whole takes more than L{REPR_MAXLINES}
-        lines, then it will be truncated (with an ellipsis marker).
-        This function will never return L{UNKNOWN} or C{None}.
-    
-        @rtype: L{ColorizedPyvalRepr}
-        """
-        # Use self.__pyval_repr to cache the result.
-        if not hasattr(self, '_ValueDoc__pyval_repr'):
-            self.__pyval_repr = epydoc.markup.pyval_repr.colorize_pyval(
-                self.pyval, self.parse_repr, self.REPR_MIN_SCORE,
-                self.REPR_LINELEN, self.REPR_MAXLINES, linebreakok=True)
-        return self.__pyval_repr
-
-    def summary_pyval_repr(self, max_len=None):
-        """
-        Return a single-line formatted representation of the Python
-        object described by this C{ValueDoc}.  This representation may
-        include data from introspection or parsing, and is authorative
-        as 'the best way to summarize a Python value.'  If the
-        representation takes more then L{SUMMARY_REPR_LINELEN}
-        characters, then it will be truncated (with an ellipsis
-        marker).  This function will never return L{UNKNOWN} or
-        C{None}.
-    
-        @rtype: L{ColorizedPyvalRepr}
-        """
-        # If max_len is specified, then do *not* cache the result.
-        if max_len is not None:
-            return epydoc.markup.pyval_repr.colorize_pyval(
-                self.pyval, self.parse_repr, self.REPR_MIN_SCORE,
-                max_len, maxlines=1, linebreakok=False)
-            
-        # Use self.__summary_pyval_repr to cache the result.
-        if not hasattr(self, '_ValueDoc__summary_pyval_repr'):
-            self.__summary_pyval_repr = epydoc.markup.pyval_repr.colorize_pyval(
-                self.pyval, self.parse_repr, self.REPR_MIN_SCORE,
-                self.SUMMARY_REPR_LINELEN, maxlines=1, linebreakok=False)
-        return self.__summary_pyval_repr
-    #} end of "value representation" group
-
-    def apidoc_links(self, **filters):
-        return []
-
-class GenericValueDoc(ValueDoc):
-    """
-    API documentation about a 'generic' value, i.e., one that does not
-    have its own docstring or any information other than its value and
-    parse representation.  C{GenericValueDoc}s do not get assigned
-    cannonical names.
-    """
-    canonical_name = None
-    
-    def is_detailed(self):
-        return (not self.summary_pyval_repr().is_complete)
-
-class NamespaceDoc(ValueDoc):
-    """
-    API documentation information about a singe Python namespace
-    value.  (I.e., a module or a class).
-    """
-    #{ Information about Variables
-    variables = UNKNOWN
-    """@ivar: The contents of the namespace, encoded as a
-        dictionary mapping from identifiers to C{VariableDoc}s.  This
-        dictionary contains all names defined by the namespace,
-        including imported variables, aliased variables, and variables
-        inherited from base classes (once L{inherit_docs()
-        <epydoc.docbuilder.inherit_docs>} has added them).
-       @type: C{dict} from C{string} to L{VariableDoc}"""
-    sorted_variables = UNKNOWN
-    """@ivar: A list of all variables defined by this
-       namespace, in sorted order.  The elements of this list should
-       exactly match the values of L{variables}.  The sort order for
-       this list is defined as follows:
-          - Any variables listed in a C{@sort} docstring field are
-            listed in the order given by that field.
-          - These are followed by any variables that were found while
-            parsing the source code, in the order in which they were
-            defined in the source file.
-          - Finally, any remaining variables are listed in
-            alphabetical order.
-       @type: C{list} of L{VariableDoc}"""
-    sort_spec = UNKNOWN
-    """@ivar: The order in which variables should be listed,
-       encoded as a list of names.  Any variables whose names are not
-       included in this list should be listed alphabetically,
-       following the variables that are included.
-       @type: C{list} of C{str}"""
-    group_specs = UNKNOWN
-    """@ivar: The groups that are defined by this namespace's
-       docstrings.  C{group_specs} is encoded as an ordered list of
-       tuples C{(group_name, elt_names)}, where C{group_name} is the
-        
-       name of a group and C{elt_names} is a list of element names in
-       that group.  (An element can be a variable or a submodule.)  A
-       '*' in an element name will match any string of characters.
-       @type: C{list} of C{(str,list)}"""
-    variable_groups = UNKNOWN
-    """@ivar: A dictionary specifying what group each
-       variable belongs to.  The keys of the dictionary are group
-       names, and the values are lists of C{VariableDoc}s.  The order
-       that groups should be listed in should be taken from
-       L{group_specs}.
-       @type: C{dict} from C{str} to C{list} of L{VariableDoc}"""
-    #} end of group "information about variables"
-
-    def __init__(self, **kwargs):
-        kwargs.setdefault('variables', {})
-        APIDoc.__init__(self, **kwargs)
-        assert self.variables is not UNKNOWN
-
-    def is_detailed(self):
-        return True
-
-    def apidoc_links(self, **filters):
-        variables = filters.get('variables', True)
-        imports = filters.get('imports', True)
-        private = filters.get('private', True)
-        if variables and imports and private:
-            return self.variables.values() # list the common case first.
-        elif not variables:
-            return []
-        elif not imports and not private:
-            return [v for v in self.variables.values() if
-                    v.is_imported != True and v.is_public != False]
-        elif not private:
-            return [v for v in self.variables.values() if
-                    v.is_public != False]
-        elif not imports:
-            return [v for v in self.variables.values() if
-                    v.is_imported != True]
-        assert 0, 'this line should be unreachable'
-
-    def init_sorted_variables(self):
-        """
-        Initialize the L{sorted_variables} attribute, based on the
-        L{variables} and L{sort_spec} attributes.  This should usually
-        be called after all variables have been added to C{variables}
-        (including any inherited variables for classes).  
-        """
-        unsorted = self.variables.copy()
-        self.sorted_variables = []
-    
-        # Add any variables that are listed in sort_spec
-        if self.sort_spec is not UNKNOWN:
-            unused_idents = set(self.sort_spec)
-            for ident in self.sort_spec:
-                if ident in unsorted:
-                    self.sorted_variables.append(unsorted.pop(ident))
-                    unused_idents.discard(ident)
-                elif '*' in ident:
-                    regexp = re.compile('^%s$' % ident.replace('*', '(.*)'))
-                    # sort within matching group?
-                    for name, var_doc in unsorted.items():
-                        if regexp.match(name):
-                            self.sorted_variables.append(unsorted.pop(name))
-                            unused_idents.discard(ident)
-            for ident in unused_idents:
-                if ident not in ['__all__', '__docformat__', '__path__']:
-                    log.warning("@sort: %s.%s not found" %
-                                (self.canonical_name, ident))
-                    
-    
-        # Add any remaining variables in alphabetical order.
-        var_docs = unsorted.items()
-        var_docs.sort()
-        for name, var_doc in var_docs:
-            self.sorted_variables.append(var_doc)
-
-    def init_variable_groups(self):
-        """
-        Initialize the L{variable_groups} attribute, based on the
-        L{sorted_variables} and L{group_specs} attributes.
-        """
-        if self.sorted_variables is UNKNOWN:
-            self.init_sorted_variables()
-        assert len(self.sorted_variables) == len(self.variables)
-
-        elts = [(v.name, v) for v in self.sorted_variables]
-        self._unused_groups = dict([(n,set(i)) for (n,i) in self.group_specs])
-        self.variable_groups = self._init_grouping(elts)
-
-    def group_names(self):
-        """
-        Return a list of the group names defined by this namespace, in
-        the order in which they should be listed, with no duplicates.
-        """
-        name_list = ['']
-        name_set = set()
-        for name, spec in self.group_specs:
-            if name not in name_set:
-                name_set.add(name)
-                name_list.append(name)
-        return name_list
-
-    def _init_grouping(self, elts):
-        """
-        Divide a given a list of APIDoc objects into groups, as
-        specified by L{self.group_specs}.
-
-        @param elts: A list of tuples C{(name, apidoc)}.
-        
-        @return: A list of tuples C{(groupname, elts)}, where
-        C{groupname} is the name of a group and C{elts} is a list of
-        C{APIDoc}s in that group.  The first tuple has name C{''}, and
-        is used for ungrouped elements.  The remaining tuples are
-        listed in the order that they appear in C{self.group_specs}.
-        Within each tuple, the elements are listed in the order that
-        they appear in C{api_docs}.
-        """
-        # Make the common case fast.
-        if len(self.group_specs) == 0:
-            return {'': [elt[1] for elt in elts]}
-
-        ungrouped = set([elt_doc for (elt_name, elt_doc) in elts])
-
-        ungrouped = dict(elts)
-        groups = {}
-        for elt_name, elt_doc in elts:
-            for (group_name, idents) in self.group_specs:
-                group = groups.setdefault(group_name, [])
-                unused_groups = self._unused_groups[group_name]
-                for ident in idents:
-                    if re.match('^%s$' % ident.replace('*', '(.*)'), elt_name):
-                        unused_groups.discard(ident)
-                        if elt_name in ungrouped:
-                            group.append(ungrouped.pop(elt_name))
-                        else:
-                            log.warning("%s.%s in multiple groups" %
-                                        (self.canonical_name, elt_name))
-
-        # Convert ungrouped from an unordered set to an ordered list.
-        groups[''] = [elt_doc for (elt_name, elt_doc) in elts
-                      if elt_name in ungrouped]
-        return groups
-    
-    def report_unused_groups(self):
-        """
-        Issue a warning for any @group items that were not used by
-        L{_init_grouping()}.
-        """
-        for (group, unused_idents) in self._unused_groups.items():
-            for ident in unused_idents:
-                log.warning("@group %s: %s.%s not found" %
-                            (group, self.canonical_name, ident))
-                        
-class ModuleDoc(NamespaceDoc):
-    """
-    API documentation information about a single module.
-    """
-    #{ Information about the Module
-    filename = UNKNOWN
-    """@ivar: The name of the file that defines the module.
-       @type: C{string}"""
-    docformat = UNKNOWN
-    """@ivar: The markup language used by docstrings in this module.
-       @type: C{string}"""
-    #{ Information about Submodules
-    submodules = UNKNOWN
-    """@ivar: Modules contained by this module (if this module
-       is a package).  (Note: on rare occasions, a module may have a
-       submodule that is shadowed by a variable with the same name.)
-       @type: C{list} of L{ModuleDoc}"""
-    submodule_groups = UNKNOWN
-    """@ivar: A dictionary specifying what group each
-       submodule belongs to.  The keys of the dictionary are group
-       names, and the values are lists of C{ModuleDoc}s.  The order
-       that groups should be listed in should be taken from
-       L{group_specs}.
-       @type: C{dict} from C{str} to C{list} of L{ModuleDoc}"""
-    #{ Information about Packages
-    package = UNKNOWN
-    """@ivar: API documentation for the module's containing package.
-       @type: L{ModuleDoc}"""
-    is_package = UNKNOWN
-    """@ivar: True if this C{ModuleDoc} describes a package.
-       @type: C{bool}"""
-    path = UNKNOWN
-    """@ivar: If this C{ModuleDoc} describes a package, then C{path}
-       contains a list of directories that constitute its path (i.e.,
-       the value of its C{__path__} variable).
-       @type: C{list} of C{str}"""
-    #{ Information about Imported Variables
-    imports = UNKNOWN
-    """@ivar: A list of the source names of variables imported into
-       this module.  This is used to construct import graphs.
-       @type: C{list} of L{DottedName}"""
-    #}
-
-    def apidoc_links(self, **filters):
-        val_docs = NamespaceDoc.apidoc_links(self, **filters)
-        if (filters.get('packages', True) and
-            self.package not in (None, UNKNOWN)):
-            val_docs.append(self.package)
-        if (filters.get('submodules', True) and
-            self.submodules not in (None, UNKNOWN)):
-            val_docs += self.submodules
-        return val_docs
-
-    def init_submodule_groups(self):
-        """
-        Initialize the L{submodule_groups} attribute, based on the
-        L{submodules} and L{group_specs} attributes.
-        """
-        if self.submodules in (None, UNKNOWN):
-            return
-        self.submodules = sorted(self.submodules,
-                                 key=lambda m:m.canonical_name)
-        elts = [(m.canonical_name[-1], m) for m in self.submodules]
-        self.submodule_groups = self._init_grouping(elts)
-
-    def select_variables(self, group=None, value_type=None, public=None,
-                         imported=None, detailed=None):
-        """
-        Return a specified subset of this module's L{sorted_variables}
-        list.  If C{value_type} is given, then only return variables
-        whose values have the specified type.  If C{group} is given,
-        then only return variables that belong to the specified group.
-
-        @require: The L{sorted_variables}, L{variable_groups}, and
-            L{submodule_groups} attributes must be initialized before
-            this method can be used.  See L{init_sorted_variables()},
-            L{init_variable_groups()}, and L{init_submodule_groups()}.
-
-        @param value_type: A string specifying the value type for
-            which variables should be returned.  Valid values are:
-              - 'class' - variables whose values are classes or types.
-              - 'function' - variables whose values are functions.
-              - 'other' - variables whose values are not classes,
-                 exceptions, types, or functions.
-        @type value_type: C{string}
-        
-        @param group: The name of the group for which variables should
-            be returned.  A complete list of the groups defined by
-            this C{ModuleDoc} is available in the L{group_names}
-            instance variable.  The first element of this list is
-            always the special group name C{''}, which is used for
-            variables that do not belong to any group.
-        @type group: C{string}
-
-        @param detailed: If True (False), return only the variables
-            deserving (not deserving) a detailed informative box.
-            If C{None}, don't care.
-        @type detailed: C{bool}
-        """
-        if (self.sorted_variables is UNKNOWN or 
-            self.variable_groups is UNKNOWN):
-            raise ValueError('sorted_variables and variable_groups '
-                             'must be initialized first.')
-        
-        if group is None: var_list = self.sorted_variables
-        else:
-            var_list = self.variable_groups.get(group, self.sorted_variables)
-
-        # Public/private filter (Count UNKNOWN as public)
-        if public is True:
-            var_list = [v for v in var_list if v.is_public is not False]
-        elif public is False:
-            var_list = [v for v in var_list if v.is_public is False]
-
-        # Imported filter (Count UNKNOWN as non-imported)
-        if imported is True:
-            var_list = [v for v in var_list if v.is_imported is True]
-        elif imported is False:
-            var_list = [v for v in var_list if v.is_imported is not True]
-
-        # Detailed filter
-        if detailed is True:
-            var_list = [v for v in var_list if v.is_detailed() is True]
-        elif detailed is False:
-            var_list = [v for v in var_list if v.is_detailed() is not True]
-
-        # [xx] Modules are not currently included in any of these
-        # value types.
-        if value_type is None:
-            return var_list
-        elif value_type == 'class':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, ClassDoc))]
-        elif value_type == 'function':
-            return [var_doc for var_doc in var_list
-                    if isinstance(var_doc.value, RoutineDoc)]
-        elif value_type == 'other':
-            return [var_doc for var_doc in var_list
-                    if not isinstance(var_doc.value,
-                                      (ClassDoc, RoutineDoc, ModuleDoc))]
-        else:
-            raise ValueError('Bad value type %r' % value_type)
-
-class ClassDoc(NamespaceDoc):
-    """
-    API documentation information about a single class.
-    """
-    #{ Information about Base Classes
-    bases = UNKNOWN
-    """@ivar: API documentation for the class's base classes.
-    @type: C{list} of L{ClassDoc}"""
-    #{ Information about Subclasses
-    subclasses = UNKNOWN
-    """@ivar: API documentation for the class's known subclasses.
-    @type: C{list} of L{ClassDoc}"""
-    #}
-
-    def apidoc_links(self, **filters):
-        val_docs = NamespaceDoc.apidoc_links(self, **filters)
-        if (filters.get('bases', True) and 
-            self.bases not in (None, UNKNOWN)):
-            val_docs += self.bases
-        if (filters.get('subclasses', True) and
-            self.subclasses not in (None, UNKNOWN)):
-            val_docs += self.subclasses
-        return val_docs
-    
-    def is_type(self):
-        if self.canonical_name == DottedName('type'): return True
-        if self.bases is UNKNOWN: return False
-        for base in self.bases:
-            if isinstance(base, ClassDoc) and base.is_type():
-                return True
-        return False
-    
-    def is_exception(self):
-        if self.canonical_name == DottedName('Exception'): return True
-        if self.bases is UNKNOWN: return False
-        for base in self.bases:
-            if isinstance(base, ClassDoc) and base.is_exception():
-                return True
-        return False
-    
-    def is_newstyle_class(self):
-        if self.canonical_name == DottedName('object'): return True
-        if self.bases is UNKNOWN: return False
-        for base in self.bases:
-            if isinstance(base, ClassDoc) and base.is_newstyle_class():
-                return True
-        return False
-
-    def mro(self, warn_about_bad_bases=False):
-        if self.is_newstyle_class():
-            return self._c3_mro(warn_about_bad_bases)
-        else:
-            return self._dfs_bases([], set(), warn_about_bad_bases)
-                
-    def _dfs_bases(self, mro, seen, warn_about_bad_bases):
-        if self in seen: return mro
-        mro.append(self)
-        seen.add(self)
-        if self.bases is not UNKNOWN:
-            for base in self.bases:
-                if isinstance(base, ClassDoc) and base.proxy_for is None:
-                    base._dfs_bases(mro, seen, warn_about_bad_bases)
-                elif warn_about_bad_bases:
-                    self._report_bad_base(base)
-        return mro
-
-    def _c3_mro(self, warn_about_bad_bases):
-        """
-        Compute the class precedence list (mro) according to C3.
-        @seealso: U{http://www.python.org/2.3/mro.html}
-        """
-        bases = [base for base in self.bases if isinstance(base, ClassDoc)]
-        if len(bases) != len(self.bases) and warn_about_bad_bases:
-            for base in self.bases:
-                if (not isinstance(base, ClassDoc) or
-                    base.proxy_for is not None):
-                    self._report_bad_base(base)
-        w = [warn_about_bad_bases]*len(bases)
-        return self._c3_merge([[self]] + map(ClassDoc._c3_mro, bases, w) +
-                              [list(bases)])
-
-    def _report_bad_base(self, base):
-        if not isinstance(base, ClassDoc):
-            if not isinstance(base, GenericValueDoc):
-                base_name = base.canonical_name
-            elif base.parse_repr is not UNKNOWN:
-                base_name = base.parse_repr
-            else:
-                base_name = '%r' % base
-            log.warning("%s's base %s is not a class" %
-                        (self.canonical_name, base_name))
-        elif base.proxy_for is not None:
-            log.warning("No information available for %s's base %s" %
-                        (self.canonical_name, base.proxy_for))
-
-    def _c3_merge(self, seqs):
-        """
-        Helper function for L{_c3_mro}.
-        """
-        res = []
-        while 1:
-          nonemptyseqs=[seq for seq in seqs if seq]
-          if not nonemptyseqs: return res
-          for seq in nonemptyseqs: # find merge candidates among seq heads
-              cand = seq[0]
-              nothead=[s for s in nonemptyseqs if cand in s[1:]]
-              if nothead: cand=None #reject candidate
-              else: break
-          if not cand: raise "Inconsistent hierarchy"
-          res.append(cand)
-          for seq in nonemptyseqs: # remove cand
-              if seq[0] == cand: del seq[0]
-    
-    def select_variables(self, group=None, value_type=None, inherited=None,
-                         public=None, imported=None, detailed=None):
-        """
-        Return a specified subset of this class's L{sorted_variables}
-        list.  If C{value_type} is given, then only return variables
-        whose values have the specified type.  If C{group} is given,
-        then only return variables that belong to the specified group.
-        If C{inherited} is True, then only return inherited variables;
-        if C{inherited} is False, then only return local variables.
-
-        @require: The L{sorted_variables} and L{variable_groups}
-            attributes must be initialized before this method can be
-            used.  See L{init_sorted_variables()} and
-            L{init_variable_groups()}.
-
-        @param value_type: A string specifying the value type for
-            which variables should be returned.  Valid values are:
-              - 'instancemethod' - variables whose values are
-                instance methods.
-              - 'classmethod' - variables whose values are class
-                methods.
-              - 'staticmethod' - variables whose values are static
-                methods.
-              - 'properties' - variables whose values are properties.
-              - 'class' - variables whose values are nested classes
-                (including exceptions and types).
-              - 'instancevariable' - instance variables.  This includes
-                any variables that are explicitly marked as instance
-                variables with docstring fields; and variables with
-                docstrings that are initialized in the constructor.
-              - 'classvariable' - class variables.  This includes any
-                variables that are not included in any of the above
-                categories.
-        @type value_type: C{string}
-        
-        @param group: The name of the group for which variables should
-            be returned.  A complete list of the groups defined by
-            this C{ClassDoc} is available in the L{group_names}
-            instance variable.  The first element of this list is
-            always the special group name C{''}, which is used for
-            variables that do not belong to any group.
-        @type group: C{string}
-
-        @param inherited: If C{None}, then return both inherited and
-            local variables; if C{True}, then return only inherited
-            variables; if C{False}, then return only local variables.
-
-        @param detailed: If True (False), return only the variables
-            deserving (not deserving) a detailed informative box.
-            If C{None}, don't care.
-        @type detailed: C{bool}
-        """
-        if (self.sorted_variables is UNKNOWN or 
-            self.variable_groups is UNKNOWN):
-            raise ValueError('sorted_variables and variable_groups '
-                             'must be initialized first.')
-        
-        if group is None: var_list = self.sorted_variables
-        else: var_list = self.variable_groups[group]
-
-        # Public/private filter (Count UNKNOWN as public)
-        if public is True:
-            var_list = [v for v in var_list if v.is_public is not False]
-        elif public is False:
-            var_list = [v for v in var_list if v.is_public is False]
-
-        # Inherited filter (Count UNKNOWN as non-inherited)
-        if inherited is None: pass
-        elif inherited:
-            var_list = [v for v in var_list if v.container != self]
-        else:
-            var_list = [v for v in var_list if v.container == self ]
-
-        # Imported filter (Count UNKNOWN as non-imported)
-        if imported is True:
-            var_list = [v for v in var_list if v.is_imported is True]
-        elif imported is False:
-            var_list = [v for v in var_list if v.is_imported is not True]
-
-        # Detailed filter
-        if detailed is True:
-            var_list = [v for v in var_list if v.is_detailed() is True]
-        elif detailed is False:
-            var_list = [v for v in var_list if v.is_detailed() is not True]
-
-        if value_type is None:
-            return var_list
-        elif value_type == 'method':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, RoutineDoc) and
-                        var_doc.is_instvar in (False, UNKNOWN))]
-        elif value_type == 'instancemethod':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, RoutineDoc) and
-                        not isinstance(var_doc.value, ClassMethodDoc) and
-                        not isinstance(var_doc.value, StaticMethodDoc) and
-                        var_doc.is_instvar in (False, UNKNOWN))]
-        elif value_type == 'classmethod':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, ClassMethodDoc) and
-                        var_doc.is_instvar in (False, UNKNOWN))]
-        elif value_type == 'staticmethod':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, StaticMethodDoc) and
-                        var_doc.is_instvar in (False, UNKNOWN))]
-        elif value_type == 'property':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, PropertyDoc) and
-                        var_doc.is_instvar in (False, UNKNOWN))]
-        elif value_type == 'class':
-            return [var_doc for var_doc in var_list
-                    if (isinstance(var_doc.value, ClassDoc) and
-                        var_doc.is_instvar in (False, UNKNOWN))]
-        elif value_type == 'instancevariable':
-            return [var_doc for var_doc in var_list
-                    if var_doc.is_instvar is True]
-        elif value_type == 'classvariable':
-            return [var_doc for var_doc in var_list
-                    if (var_doc.is_instvar in (False, UNKNOWN) and
-                        not isinstance(var_doc.value,
-                                       (RoutineDoc, ClassDoc, PropertyDoc)))]
-        else:
-            raise ValueError('Bad value type %r' % value_type)
-
-class RoutineDoc(ValueDoc):
-    """
-    API documentation information about a single routine.
-    """
-    #{ Signature
-    posargs = UNKNOWN
-    """@ivar: The names of the routine's positional arguments.
-       If an argument list contains \"unpacking\" arguments, then
-       their names will be specified using nested lists.  E.g., if
-       a function's argument list is C{((x1,y1), (x2,y2))}, then
-       posargs will be C{[['x1','y1'], ['x2','y2']]}.
-       @type: C{list}"""
-    posarg_defaults = UNKNOWN
-    """@ivar: API documentation for the positional arguments'
-       default values.  This list has the same length as C{posargs}, and
-       each element of C{posarg_defaults} describes the corresponding
-       argument in C{posargs}.  For positional arguments with no default,
-       C{posargs_defaults} will contain None.
-       @type: C{list} of C{ValueDoc} or C{None}"""
-    vararg = UNKNOWN
-    """@ivar: The name of the routine's vararg argument, or C{None} if
-       it has no vararg argument.
-       @type: C{string} or C{None}"""
-    kwarg = UNKNOWN
-    """@ivar: The name of the routine's keyword argument, or C{None} if
-       it has no keyword argument.
-       @type: C{string} or C{None}"""
-    lineno = UNKNOWN # used to look up profiling info from pstats.
-    """@ivar: The line number of the first line of the function's
-       signature.  For Python functions, this is equal to
-       C{func.func_code.co_firstlineno}.  The first line of a file
-       is considered line 1.
-       @type: C{int}"""
-    #} end of "signature" group
-
-    #{ Decorators
-    decorators = UNKNOWN
-    """@ivar: A list of names of decorators that were applied to this
-       routine, in the order that they are listed in the source code.
-       (I.e., in the reverse of the order that they were applied in.)
-       @type: C{list} of C{string}"""
-    #} end of "decorators" group
-
-    #{ Information Extracted from Docstrings
-    arg_descrs = UNKNOWN
-    """@ivar: A list of descriptions of the routine's
-       arguments.  Each element of this list is a tuple C{(args,
-       descr)}, where C{args} is a list of argument names; and
-       C{descr} is a L{ParsedDocstring
-       <epydoc.markup.ParsedDocstring>} describing the argument(s)
-       specified by C{arg}.
-       @type: C{list}"""
-    arg_types = UNKNOWN
-    """@ivar: Descriptions of the expected types for the
-       routine's arguments, encoded as a dictionary mapping from
-       argument names to type descriptions.
-       @type: C{dict} from C{string} to L{ParsedDocstring
-       <epydoc.markup.ParsedDocstring>}"""
-    return_descr = UNKNOWN
-    """@ivar: A description of the value returned by this routine.
-       @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
-    return_type = UNKNOWN
-    """@ivar: A description of expected type for the value
-       returned by this routine.
-       @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
-    exception_descrs = UNKNOWN
-    """@ivar: A list of descriptions of exceptions
-       that the routine might raise.  Each element of this list is a
-       tuple C{(exc, descr)}, where C{exc} is a string contianing the
-       exception name; and C{descr} is a L{ParsedDocstring
-       <epydoc.markup.ParsedDocstring>} describing the circumstances
-       under which the exception specified by C{exc} is raised.
-       @type: C{list}"""
-    #} end of "information extracted from docstrings" group
-    callgraph_uid = None
-    """@ivar: L{DotGraph}.uid of the call graph for the function.
-       @type: C{str}"""
-
-    def is_detailed(self):
-        if super(RoutineDoc, self).is_detailed():
-            return True
-
-        if self.arg_descrs not in (None, UNKNOWN) and self.arg_descrs:
-            return True
-
-        if self.arg_types not in (None, UNKNOWN) and self.arg_types:
-            return True
-
-        if self.return_descr not in (None, UNKNOWN):
-            return True
-
-        if self.exception_descrs not in (None, UNKNOWN) and self.exception_descrs:
-            return True
-
-        if (self.decorators not in (None, UNKNOWN)
-            and [ d for d in self.decorators
-                 if d not in ('classmethod', 'staticmethod') ]):
-            return True
-
-        return False
-
-    def all_args(self):
-        """
-        @return: A list of the names of all arguments (positional,
-        vararg, and keyword), in order.  If a positional argument
-        consists of a tuple of names, then that tuple will be
-        flattened.
-        """
-        if self.posargs is UNKNOWN:
-            return UNKNOWN
-            
-        all_args = _flatten(self.posargs)
-        if self.vararg not in (None, UNKNOWN):
-            all_args.append(self.vararg)
-        if self.kwarg not in (None, UNKNOWN):
-            all_args.append(self.kwarg)
-        return all_args
-
-def _flatten(lst, out=None):
-    """
-    Return a flattened version of C{lst}.
-    """
-    if out is None: out = []
-    for elt in lst:
-        if isinstance(elt, (list,tuple)):
-            _flatten(elt, out)
-        else:
-            out.append(elt)
-    return out
-
-class ClassMethodDoc(RoutineDoc): pass
-class StaticMethodDoc(RoutineDoc): pass
-
-class PropertyDoc(ValueDoc):
-    """
-    API documentation information about a single property.
-    """
-    #{ Property Access Functions
-    fget = UNKNOWN
-    """@ivar: API documentation for the property's get function.
-       @type: L{RoutineDoc}"""
-    fset = UNKNOWN
-    """@ivar: API documentation for the property's set function.
-       @type: L{RoutineDoc}"""
-    fdel = UNKNOWN
-    """@ivar: API documentation for the property's delete function.
-       @type: L{RoutineDoc}"""
-    #}
-    #{ Information Extracted from Docstrings
-    type_descr = UNKNOWN
-    """@ivar: A description of the property's expected type, extracted
-       from its docstring.
-       @type: L{ParsedDocstring<epydoc.markup.ParsedDocstring>}"""
-    #} end of "information extracted from docstrings" group
-
-    def apidoc_links(self, **filters):
-        val_docs = []
-        if self.fget not in (None, UNKNOWN): val_docs.append(self.fget)
-        if self.fset not in (None, UNKNOWN): val_docs.append(self.fset)
-        if self.fdel not in (None, UNKNOWN): val_docs.append(self.fdel)
-        return val_docs
-
-    def is_detailed(self):
-        if super(PropertyDoc, self).is_detailed():
-            return True
-
-        if self.fget not in (None, UNKNOWN) and self.fget.pyval is not None:
-             return True
-        if self.fset not in (None, UNKNOWN) and self.fset.pyval is not None:
-             return True
-        if self.fdel not in (None, UNKNOWN) and self.fdel.pyval is not None:
-             return True
-
-        return False
-
-######################################################################
-## Index
-######################################################################
-
-class DocIndex:
-    """
-    [xx] out of date.
-    
-    An index that .. hmm...  it *can't* be used to access some things,
-    cuz they're not at the root level.  Do I want to add them or what?
-    And if so, then I have a sort of a new top level.  hmm..  so
-    basically the question is what to do with a name that's not in the
-    root var's name space.  2 types:
-      - entirely outside (eg os.path)
-      - inside but not known (eg a submodule that we didn't look at?)
-      - container of current thing not examined?
-    
-    An index of all the C{APIDoc} objects that can be reached from a
-    root set of C{ValueDoc}s.  
-    
-    The members of this index can be accessed by dotted name.  In
-    particular, C{DocIndex} defines two mappings, accessed via the
-    L{get_vardoc()} and L{get_valdoc()} methods, which can be used to
-    access C{VariableDoc}s or C{ValueDoc}s respectively by name.  (Two
-    separate mappings are necessary because a single name can be used
-    to refer to both a variable and to the value contained by that
-    variable.)
-
-    Additionally, the index defines two sets of C{ValueDoc}s:
-    \"reachable C{ValueDoc}s\" and \"contained C{ValueDoc}s\".  The
-    X{reachable C{ValueDoc}s} are defined as the set of all
-    C{ValueDoc}s that can be reached from the root set by following
-    I{any} sequence of pointers to C{ValueDoc}s or C{VariableDoc}s.
-    The X{contained C{ValueDoc}s} are defined as the set of all
-    C{ValueDoc}s that can be reached from the root set by following
-    only the C{ValueDoc} pointers defined by non-imported
-    C{VariableDoc}s.  For example, if the root set contains a module
-    C{m}, then the contained C{ValueDoc}s includes the C{ValueDoc}s
-    for any functions, variables, or classes defined in that module,
-    as well as methods and variables defined in classes defined in the
-    module.  The reachable C{ValueDoc}s includes all of those
-    C{ValueDoc}s, as well as C{ValueDoc}s for any values imported into
-    the module, and base classes for classes defined in the module.
-    """
-
-    def __init__(self, root):
-        """
-        Create a new documentation index, based on the given root set
-        of C{ValueDoc}s.  If any C{APIDoc}s reachable from the root
-        set does not have a canonical name, then it will be assigned
-        one.  etc.
-        
-        @param root: A list of C{ValueDoc}s.
-        """
-        for apidoc in root:
-            if apidoc.canonical_name in (None, UNKNOWN):
-                raise ValueError("All APIdocs passed to DocIndexer "
-                                 "must already have canonical names.")
-        
-        # Initialize the root items list.  We sort them by length in
-        # ascending order.  (This ensures that variables will shadow
-        # submodules when appropriate.)
-        # When the elements name is the same, list in alphabetical order:
-        # this is needed by the check for duplicates below.
-        self.root = sorted(root,
-            key=lambda d: (len(d.canonical_name), d.canonical_name))
-        """The list of C{ValueDoc}s to document.
-            @type: C{list}"""
-
-        # Drop duplicated modules
-        # [xx] maybe what causes duplicates should be fixed instead.
-        #      If fixed, adjust the sort here above: sorting by names will not
-        #      be required anymore
-        i = 1
-        while i < len(self.root):
-            if self.root[i-1] is self.root[i]:
-                del self.root[i]
-            else:
-                i += 1
-
-        self.mlclasses = self._get_module_classes(self.root)
-        """A mapping from class names to L{ClassDoc}. Contains
-           classes defined at module level for modules in L{root}
-           and which can be used as fallback by L{find()} if looking
-           in containing namespaces fails.
-           @type: C{dict} from C{str} to L{ClassDoc} or C{list}"""
-
-        self.callers = None
-        """A dictionary mapping from C{RoutineDoc}s in this index
-           to lists of C{RoutineDoc}s for the routine's callers.
-           This dictionary is initialized by calling
-           L{read_profiling_info()}.
-           @type: C{list} of L{RoutineDoc}"""
-        
-        self.callees = None
-        """A dictionary mapping from C{RoutineDoc}s in this index
-           to lists of C{RoutineDoc}s for the routine's callees.
-           This dictionary is initialized by calling
-           L{read_profiling_info()}.
-           @type: C{list} of L{RoutineDoc}"""
-
-        self._funcid_to_doc = {}
-        """A mapping from C{profile} function ids to corresponding
-           C{APIDoc} objects.  A function id is a tuple of the form
-           C{(filename, lineno, funcname)}.  This is used to update
-           the L{callers} and L{callees} variables."""
-
-        self._container_cache = {}
-        """A cache for the L{container()} method, to increase speed."""
-
-        self._get_cache = {}
-        """A cache for the L{get_vardoc()} and L{get_valdoc()} methods,
-        to increase speed."""
-
-    #////////////////////////////////////////////////////////////
-    # Lookup methods
-    #////////////////////////////////////////////////////////////
-    # [xx]
-    # Currently these only work for things reachable from the
-    # root... :-/  I might want to change this so that imported
-    # values can be accessed even if they're not contained.  
-    # Also, I might want canonical names to not start with ??
-    # if the thing is a top-level imported module..?
-
-    def get_vardoc(self, name):
-        """
-        Return the C{VariableDoc} with the given name, or C{None} if this
-        index does not contain a C{VariableDoc} with the given name.
-        """
-        var, val = self._get(name)
-        return var
-
-    def get_valdoc(self, name):
-        """
-        Return the C{ValueDoc} with the given name, or C{None} if this
-        index does not contain a C{ValueDoc} with the given name.
-        """
-        var, val = self._get(name)
-        return val
-
-    def _get(self, name):
-        """
-        A helper function that's used to implement L{get_vardoc()}
-        and L{get_valdoc()}.
-        """
-        # Convert name to a DottedName, if necessary.
-        if not isinstance(name, DottedName):
-            name = DottedName(name)
-
-        # Check if the result is cached.
-        val = self._get_cache.get(name)
-        if val is not None: return val
-
-        # Look for an element in the root set whose name is a prefix
-        # of `name`.  If we can't find one, then return None.
-        for root_valdoc in self.root:
-            if root_valdoc.canonical_name.dominates(name):
-                # Starting at the root valdoc, walk down the variable/
-                # submodule chain until we find the requested item.
-                var_doc = None
-                val_doc = root_valdoc
-                for identifier in name[len(root_valdoc.canonical_name):]:
-                    if val_doc is None: break
-                    var_doc, val_doc = self._get_from(val_doc, identifier)
-                else:
-                    # If we found it, then return.
-                    if var_doc is not None or val_doc is not None:
-                        self._get_cache[name] = (var_doc, val_doc)
-                        return var_doc, val_doc
-
-        # We didn't find it.
-        self._get_cache[name] = (None, None)
-        return None, None
-
-    def _get_from(self, val_doc, identifier):
-        if isinstance(val_doc, NamespaceDoc):
-            child_var = val_doc.variables.get(identifier)
-            if child_var is not None:
-                child_val = child_var.value
-                if child_val is UNKNOWN: child_val = None
-                return child_var, child_val
-
-        # If that fails, then see if it's a submodule.
-        if (isinstance(val_doc, ModuleDoc) and
-            val_doc.submodules is not UNKNOWN):
-            for submodule in val_doc.submodules:
-                if submodule.canonical_name[-1] == identifier:
-                    var_doc = None
-                    val_doc = submodule
-                    if val_doc is UNKNOWN: val_doc = None
-                    return var_doc, val_doc
-
-        return None, None
-
-    def find(self, name, context):
-        """
-        Look for an C{APIDoc} named C{name}, relative to C{context}.
-        Return the C{APIDoc} if one is found; otherwise, return
-        C{None}.  C{find} looks in the following places, in order:
-          - Function parameters (if one matches, return C{None})
-          - All enclosing namespaces, from closest to furthest.
-          - If C{name} starts with C{'self'}, then strip it off and
-            look for the remaining part of the name using C{find}
-          - Builtins
-          - Parameter attributes
-          - Classes at module level (if the name is not ambiguous)
-        
-        @type name: C{str} or L{DottedName}
-        @type context: L{APIDoc}
-        """
-        if isinstance(name, basestring):
-            name = re.sub(r'\(.*\)$', '', name.strip())
-            if re.match('^([a-zA-Z_]\w*)(\.[a-zA-Z_]\w*)*$', name):
-                name = DottedName(name)
-            else:
-                return None
-        elif not isinstance(name, DottedName):
-            raise TypeError("'name' should be a string or DottedName")
-        
-        if context is None or context.canonical_name is None:
-            container_name = []
-        else:
-            container_name = context.canonical_name
-
-        # Check for the name in all containing namespaces, starting
-        # with the closest one.
-        for i in range(len(container_name), -1, -1):
-            relative_name = container_name[:i]+name
-            # Is `name` the absolute name of a documented value?
-            # (excepting GenericValueDoc values.)
-            val_doc = self.get_valdoc(relative_name)
-            if (val_doc is not None and
-                not isinstance(val_doc, GenericValueDoc)):
-                return val_doc
-            # Is `name` the absolute name of a documented variable?
-            var_doc = self.get_vardoc(relative_name)
-            if var_doc is not None: return var_doc
-
-        # If the name begins with 'self', then try stripping that off
-        # and see if we can find the variable.
-        if name[0] == 'self':
-            doc = self.find('.'.join(name[1:]), context)
-            if doc is not None: return doc
-
-        # Is it the name of a builtin?
-        if len(name)==1 and hasattr(__builtin__, name[0]):
-            return None
-        
-        # Is it a parameter's name or an attribute of a parameter?
-        if isinstance(context, RoutineDoc):
-            all_args = context.all_args()
-            if all_args is not UNKNOWN and name[0] in all_args:
-                return None
-
-        # Is this an object directly contained by any module?
-        doc = self.mlclasses.get(name[-1])
-        if isinstance(doc, APIDoc):
-            return doc
-        elif isinstance(doc, list):
-            log.warning("%s is an ambiguous name: it may be %s" % (
-                name[-1],
-                ", ".join([ "'%s'" % d.canonical_name for d in doc ])))
-
-            # Drop this item so that the warning is reported only once.
-            # fail() will fail anyway.
-            del self.mlclasses[name[-1]]
-
-    def _get_module_classes(self, docs):
-        """
-        Gather all the classes defined in a list of modules.
-
-        Very often people refers to classes only by class name,
-        even if they are not imported in the namespace. Linking
-        to such classes will fail if we look for them only in nested
-        namespaces. Allow them to retrieve only by name.
-
-        @param docs: containers of the objects to collect
-        @type docs: C{list} of C{APIDoc}
-        @return: mapping from objects name to the object(s) with that name
-        @rtype: C{dict} from C{str} to L{ClassDoc} or C{list}
-        """
-        classes = {}
-        for doc in docs:
-            if not isinstance(doc, ModuleDoc):
-                continue
-
-            for var in doc.variables.values():
-                if not isinstance(var.value, ClassDoc):
-                    continue
-
-                val = var.value
-                if val in (None, UNKNOWN) or val.defining_module is not doc:
-                    continue
-                if val.canonical_name in (None, UNKNOWN):
-                    continue
-
-                name = val.canonical_name[-1]
-                vals = classes.get(name)
-                if vals is None:
-                    classes[name] = val
-                elif not isinstance(vals, list):
-                    classes[name] = [ vals, val ]
-                else:
-                    vals.append(val)
-
-        return classes
-
-    #////////////////////////////////////////////////////////////
-    # etc
-    #////////////////////////////////////////////////////////////
-
-    def reachable_valdocs(self, **filters):
-        """
-        Return a list of all C{ValueDoc}s that can be reached,
-        directly or indirectly from this C{DocIndex}'s root set.
-        
-        @param filters: A set of filters that can be used to prevent
-            C{reachable_valdocs} from following specific link types
-            when looking for C{ValueDoc}s that can be reached from the
-            root set.  See C{APIDoc.apidoc_links} for a more complete
-            description.
-        """
-        return reachable_valdocs(self.root, **filters)
-
-    def container(self, api_doc):
-        """
-        Return the C{ValueDoc} that contains the given C{APIDoc}, or
-        C{None} if its container is not in the index.
-        """
-        # Check if the result is cached.
-        val = self._container_cache.get(api_doc)
-        if val is not None: return val
-        
-        if isinstance(api_doc, GenericValueDoc):
-            self._container_cache[api_doc] = None
-            return None # [xx] unknown.
-        if isinstance(api_doc, VariableDoc):
-            self._container_cache[api_doc] = api_doc.container
-            return api_doc.container
-        if len(api_doc.canonical_name) == 1:
-            self._container_cache[api_doc] = None
-            return None
-        elif isinstance(api_doc, ModuleDoc) and api_doc.package is not UNKNOWN:
-            self._container_cache[api_doc] = api_doc.package
-            return api_doc.package
-        else:
-            parent = self.get_valdoc(api_doc.canonical_name.container())
-            self._container_cache[api_doc] = parent
-            return parent
-
-    #////////////////////////////////////////////////////////////
-    # Profiling information
-    #////////////////////////////////////////////////////////////
-
-    def read_profiling_info(self, profile_stats):
-        """
-        Initialize the L{callers} and L{callees} variables, given a
-        C{Stat} object from the C{pstats} module.
-        
-        @warning: This method uses undocumented data structures inside
-            of C{profile_stats}.
-        """
-        if self.callers is None: self.callers = {}
-        if self.callees is None: self.callees = {}
-        
-        # The Stat object encodes functions using `funcid`s, or
-        # tuples of (filename, lineno, funcname).  Create a mapping
-        # from these `funcid`s to `RoutineDoc`s.
-        self._update_funcid_to_doc(profile_stats)
-        
-        for callee, (cc, nc, tt, ct, callers) in profile_stats.stats.items():
-            callee = self._funcid_to_doc.get(callee)
-            if callee is None: continue
-            for caller in callers:
-                caller = self._funcid_to_doc.get(caller)
-                if caller is None: continue
-                self.callers.setdefault(callee, []).append(caller)
-                self.callees.setdefault(caller, []).append(callee)
-
-    def _update_funcid_to_doc(self, profile_stats):
-        """
-        Update the dictionary mapping from C{pstat.Stat} funciton ids to
-        C{RoutineDoc}s.  C{pstat.Stat} function ids are tuples of
-        C{(filename, lineno, funcname)}.
-        """
-        # Maps (filename, lineno, funcname) -> RoutineDoc
-        for val_doc in self.reachable_valdocs():
-            # We only care about routines.
-            if not isinstance(val_doc, RoutineDoc): continue
-            # Get the filename from the defining module.
-            module = val_doc.defining_module
-            if module is UNKNOWN or module.filename is UNKNOWN: continue
-            # Normalize the filename.
-            filename = os.path.abspath(module.filename)
-            try: filename = py_src_filename(filename)
-            except: pass
-            # Look up the stat_func_id
-            funcid = (filename, val_doc.lineno, val_doc.canonical_name[-1])
-            if funcid in profile_stats.stats:
-                self._funcid_to_doc[funcid] = val_doc
-
-######################################################################
-## Pretty Printing
-######################################################################
-
-def pp_apidoc(api_doc, doublespace=0, depth=5, exclude=(), include=(),
-              backpointers=None):
-    """
-    @return: A multiline pretty-printed string representation for the
-        given C{APIDoc}.
-    @param doublespace: If true, then extra lines will be
-        inserted to make the output more readable.
-    @param depth: The maximum depth that pp_apidoc will descend
-        into descendent VarDocs.  To put no limit on
-        depth, use C{depth=-1}.
-    @param exclude: A list of names of attributes whose values should
-        not be shown.
-    @param backpointers: For internal use.
-    """
-    pyid = id(api_doc.__dict__)
-    if backpointers is None: backpointers = {}
-    if (hasattr(api_doc, 'canonical_name') and
-        api_doc.canonical_name not in (None, UNKNOWN)):
-        name = '%s for %s' % (api_doc.__class__.__name__,
-                              api_doc.canonical_name)
-    elif getattr(api_doc, 'name', None) not in (UNKNOWN, None):
-        if (getattr(api_doc, 'container', None) not in (UNKNOWN, None) and
-            getattr(api_doc.container, 'canonical_name', None)
-            not in (UNKNOWN, None)):
-            name ='%s for %s' % (api_doc.__class__.__name__,
-                                 api_doc.container.canonical_name+
-                                 api_doc.name)
-        else:
-            name = '%s for %s' % (api_doc.__class__.__name__, api_doc.name)
-    else:
-        name = api_doc.__class__.__name__
-        
-    if pyid in backpointers:
-        return '%s [%s] (defined above)' % (name, backpointers[pyid])
-    
-    if depth == 0:
-        if hasattr(api_doc, 'name') and api_doc.name is not None:
-            return '%s...' % api_doc.name
-        else:
-            return '...'
-
-    backpointers[pyid] = len(backpointers)
-    s = '%s [%s]' % (name, backpointers[pyid])
-
-    # Only print non-empty fields:
-    fields = [field for field in api_doc.__dict__.keys()
-              if (field in include or
-                  (getattr(api_doc, field) is not UNKNOWN
-                   and field not in exclude))]
-    if include:
-        fields = [field for field in dir(api_doc)
-                  if field in include]
-    else:
-        fields = [field for field in api_doc.__dict__.keys()
-                  if (getattr(api_doc, field) is not UNKNOWN
-                      and field not in exclude)]
-    fields.sort()
-    
-    for field in fields:
-        fieldval = getattr(api_doc, field)
-        if doublespace: s += '\n |'
-        s += '\n +- %s' % field
-
-        if (isinstance(fieldval, types.ListType) and
-            len(fieldval)>0 and
-            isinstance(fieldval[0], APIDoc)):
-            s += _pp_list(api_doc, fieldval, doublespace, depth,
-                          exclude, include, backpointers,
-                          (field is fields[-1]))
-        elif (isinstance(fieldval, types.DictType) and
-              len(fieldval)>0 and 
-              isinstance(fieldval.values()[0], APIDoc)):
-            s += _pp_dict(api_doc, fieldval, doublespace, 
-                          depth, exclude, include, backpointers,
-                          (field is fields[-1]))
-        elif isinstance(fieldval, APIDoc):
-            s += _pp_apidoc(api_doc, fieldval, doublespace, depth,
-                            exclude, include, backpointers,
-                            (field is fields[-1]))
-        else:
-            s += ' = ' + _pp_val(api_doc, fieldval, doublespace,
-                                 depth, exclude, include, backpointers)
-                
-    return s
-
-def _pp_list(api_doc, items, doublespace, depth, exclude, include,
-              backpointers, is_last):
-    line1 = (is_last and ' ') or '|'
-    s = ''
-    for item in items:
-        line2 = ((item is items[-1]) and ' ') or '|'
-        joiner = '\n %s  %s ' % (line1, line2)
-        if doublespace: s += '\n %s  |' % line1
-        s += '\n %s  +- ' % line1
-        valstr = _pp_val(api_doc, item, doublespace, depth, exclude, include,
-                         backpointers)
-        s += joiner.join(valstr.split('\n'))
-    return s
-
-def _pp_dict(api_doc, dict, doublespace, depth, exclude, include,
-              backpointers, is_last):
-    items = dict.items()
-    items.sort()
-    line1 = (is_last and ' ') or '|'
-    s = ''
-    for item in items:
-        line2 = ((item is items[-1]) and ' ') or '|'
-        joiner = '\n %s  %s ' % (line1, line2)
-        if doublespace: s += '\n %s  |' % line1
-        s += '\n %s  +- ' % line1
-        valstr = _pp_val(api_doc, item[1], doublespace, depth, exclude,
-                         include, backpointers)
-        s += joiner.join(('%s => %s' % (item[0], valstr)).split('\n'))
-    return s
-
-def _pp_apidoc(api_doc, val, doublespace, depth, exclude, include,
-                backpointers, is_last):
-    line1 = (is_last and ' ') or '|'
-    s = ''
-    if doublespace: s += '\n %s  |  ' % line1
-    s += '\n %s  +- ' % line1
-    joiner = '\n %s    ' % line1
-    childstr = pp_apidoc(val, doublespace, depth-1, exclude,
-                         include, backpointers)
-    return s + joiner.join(childstr.split('\n'))
-    
-def _pp_val(api_doc, val, doublespace, depth, exclude, include, backpointers):
-    from epydoc import markup
-    if isinstance(val, APIDoc):
-        return pp_apidoc(val, doublespace, depth-1, exclude,
-                         include, backpointers)
-    elif isinstance(val, markup.ParsedDocstring):
-        valrepr = `val.to_plaintext(None)`
-        if len(valrepr) < 40: return valrepr
-        else: return valrepr[:37]+'...'
-    else:
-        valrepr = repr(val)
-        if len(valrepr) < 40: return valrepr
-        else: return valrepr[:37]+'...'
-