bee_python 0.0.1

data/tools/epydoc/docwriter/dotgraph.py

@@ -0,0 +1,1351 @@
+# epydoc -- Graph generation
+#
+# Copyright (C) 2005 Edward Loper
+# Author: Edward Loper <edloper@loper.org>
+# URL: <http://epydoc.sf.net>
+#
+# $Id: dotgraph.py,v 1.1 2009/11/26 13:20:43 casa Exp $
+
+"""
+Render Graphviz directed graphs as images.  Below are some examples.
+
+.. importgraph::
+
+.. classtree:: epydoc.apidoc.APIDoc
+
+.. packagetree:: epydoc
+
+:see: `The Graphviz Homepage
+       <http://www.research.att.com/sw/tools/graphviz/>`__
+"""
+__docformat__ = 'restructuredtext'
+
+import re
+import sys
+from epydoc import log
+from epydoc.apidoc import *
+from epydoc.util import *
+from epydoc.compat import * # Backwards compatibility
+
+# colors for graphs of APIDocs
+MODULE_BG = '#d8e8ff'
+CLASS_BG = '#d8ffe8'
+SELECTED_BG = '#ffd0d0'
+BASECLASS_BG = '#e0b0a0'
+SUBCLASS_BG = '#e0b0a0'
+ROUTINE_BG = '#e8d0b0' # maybe?
+INH_LINK_COLOR = '#800000'
+
+######################################################################
+#{ Dot Graphs
+######################################################################
+
+DOT_COMMAND = 'dot'
+"""The command that should be used to spawn dot"""
+
+class DotGraph:
+    """
+    A ``dot`` directed graph.  The contents of the graph are
+    constructed from the following instance variables:
+
+      - `nodes`: A list of `DotGraphNode`\\s, encoding the nodes
+        that are present in the graph.  Each node is characterized
+        a set of attributes, including an optional label.
+      - `edges`: A list of `DotGraphEdge`\\s, encoding the edges
+        that are present in the graph.  Each edge is characterized
+        by a set of attributes, including an optional label.
+      - `node_defaults`: Default attributes for nodes.
+      - `edge_defaults`: Default attributes for edges.
+      - `body`: A string that is appended as-is in the body of
+        the graph.  This can be used to build more complex dot
+        graphs.
+
+    The `link()` method can be used to resolve crossreference links
+    within the graph.  In particular, if the 'href' attribute of any
+    node or edge is assigned a value of the form ``<name>``, then it
+    will be replaced by the URL of the object with that name.  This
+    applies to the `body` as well as the `nodes` and `edges`.
+
+    To render the graph, use the methods `write()` and `render()`.
+    Usually, you should call `link()` before you render the graph.
+    """
+    _uids = set()
+    """A set of all uids that that have been generated, used to ensure
+    that each new graph has a unique uid."""
+
+    DEFAULT_NODE_DEFAULTS={'fontsize':10, 'fontname': 'Helvetica'}
+    DEFAULT_EDGE_DEFAULTS={'fontsize':10, 'fontname': 'Helvetica'}
+    
+    def __init__(self, title, body='', node_defaults=None,
+                 edge_defaults=None, caption=None):
+        """
+        Create a new `DotGraph`.
+        """
+        self.title = title
+        """The title of the graph."""
+
+        self.caption = caption
+        """A caption for the graph."""
+        
+        self.nodes = []
+        """A list of the nodes that are present in the graph.
+        
+        :type: ``list`` of `DotGraphNode`"""
+        
+        self.edges = []
+        """A list of the edges that are present in the graph.
+        
+        :type: ``list`` of `DotGraphEdge`"""
+
+        self.body = body
+        """A string that should be included as-is in the body of the
+        graph.
+        
+        :type: ``str``"""
+        
+        self.node_defaults = node_defaults or self.DEFAULT_NODE_DEFAULTS
+        """Default attribute values for nodes."""
+        
+        self.edge_defaults = edge_defaults or self.DEFAULT_EDGE_DEFAULTS
+        """Default attribute values for edges."""
+
+        self.uid = re.sub(r'\W', '_', title).lower()
+        """A unique identifier for this graph.  This can be used as a
+        filename when rendering the graph.  No two `DotGraph`\s will
+        have the same uid."""
+
+        # Encode the title, if necessary.
+        if isinstance(self.title, unicode):
+            self.title = self.title.encode('ascii', 'xmlcharrefreplace')
+
+        # Make sure the UID isn't too long.
+        self.uid = self.uid[:30]
+        
+        # Make sure the UID is unique
+        if self.uid in self._uids:
+            n = 2
+            while ('%s_%s' % (self.uid, n)) in self._uids: n += 1
+            self.uid = '%s_%s' % (self.uid, n)
+        self._uids.add(self.uid)
+
+    def to_html(self, image_file, image_url, center=True):
+        """
+        Return the HTML code that should be uesd to display this graph
+        (including a client-side image map).
+        
+        :param image_url: The URL of the image file for this graph;
+            this should be generated separately with the `write()` method.
+        """
+        # If dotversion >1.8.10, then we can generate the image and
+        # the cmapx with a single call to dot.  Otherwise, we need to
+        # run dot twice.
+        if get_dot_version() > [1,8,10]:
+            cmapx = self._run_dot('-Tgif', '-o%s' % image_file, '-Tcmapx')
+            if cmapx is None: return '' # failed to render
+        else:
+            if not self.write(image_file):
+                return '' # failed to render
+            cmapx = self.render('cmapx') or ''
+
+        # Decode the cmapx (dot uses utf-8)
+        try:
+            cmapx = cmapx.decode('utf-8')
+        except UnicodeDecodeError:
+            log.debug('%s: unable to decode cmapx from dot; graph will '
+                      'not have clickable regions' % image_file)
+            cmapx = ''
+
+        title = plaintext_to_html(self.title or '')
+        caption = plaintext_to_html(self.caption or '')
+        if title or caption:
+            css_class = 'graph-with-title'
+        else:
+            css_class = 'graph-without-title'
+        if len(title)+len(caption) > 80:
+            title_align = 'left'
+            table_width = ' width="600"'
+        else:
+            title_align = 'center'
+            table_width = ''
+            
+        if center: s = '<center>'
+        if title or caption:
+            s += ('<table border="0" cellpadding="0" cellspacing="0" '
+                  'class="graph"%s>\n  <tr><td align="center">\n' %
+                  table_width)
+        s += ('  %s\n  <img src="%s" alt=%r usemap="#%s" '
+              'ismap="ismap" class="%s" />\n' %
+              (cmapx.strip(), image_url, title, self.uid, css_class))
+        if title or caption:
+            s += '  </td></tr>\n  <tr><td align=%r>\n' % title_align
+            if title:
+                s += '<span class="graph-title">%s</span>' % title
+            if title and caption:
+                s += ' -- '
+            if caption:
+                s += '<span class="graph-caption">%s</span>' % caption
+            s += '\n  </td></tr>\n</table><br />'
+        if center: s += '</center>'
+        return s
+
+    def link(self, docstring_linker):
+        """
+        Replace any href attributes whose value is ``<name>`` with 
+        the url of the object whose name is ``<name>``.
+        """
+        # Link xrefs in nodes
+        self._link_href(self.node_defaults, docstring_linker)
+        for node in self.nodes:
+            self._link_href(node.attribs, docstring_linker)
+
+        # Link xrefs in edges
+        self._link_href(self.edge_defaults, docstring_linker)
+        for edge in self.nodes:
+            self._link_href(edge.attribs, docstring_linker)
+
+        # Link xrefs in body
+        def subfunc(m):
+            url = docstring_linker.url_for(m.group(1))
+            if url: return 'href="%s"%s' % (url, m.group(2))
+            else: return ''
+        self.body = re.sub("href\s*=\s*['\"]?<([\w\.]+)>['\"]?\s*(,?)",
+                           subfunc, self.body)
+
+    def _link_href(self, attribs, docstring_linker):
+        """Helper for `link()`"""
+        if 'href' in attribs:
+            m = re.match(r'^<([\w\.]+)>$', attribs['href'])
+            if m:
+                url = docstring_linker.url_for(m.group(1))
+                if url: attribs['href'] = url
+                else: del attribs['href']
+                
+    def write(self, filename, language='gif'):
+        """
+        Render the graph using the output format `language`, and write
+        the result to `filename`.
+        
+        :return: True if rendering was successful.
+        """
+        result = self._run_dot('-T%s' % language,
+                               '-o%s' % filename)
+        # Decode into unicode, if necessary.
+        if language == 'cmapx' and result is not None:
+            result = result.decode('utf-8')
+        return (result is not None)
+
+    def render(self, language='gif'):
+        """
+        Use the ``dot`` command to render this graph, using the output
+        format `language`.  Return the result as a string, or ``None``
+        if the rendering failed.
+        """
+        return self._run_dot('-T%s' % language)
+
+    def _run_dot(self, *options):
+        try:
+            result, err = run_subprocess((DOT_COMMAND,)+options,
+                                         self.to_dotfile())
+            if err: log.warning("Graphviz dot warning(s):\n%s" % err)
+        except OSError, e:
+            log.warning("Unable to render Graphviz dot graph:\n%s" % e)
+            #log.debug(self.to_dotfile())
+            return None
+
+        return result
+
+    def to_dotfile(self):
+        """
+        Return the string contents of the dot file that should be used
+        to render this graph.
+        """
+        lines = ['digraph %s {' % self.uid,
+                 'node [%s]' % ','.join(['%s="%s"' % (k,v) for (k,v)
+                                         in self.node_defaults.items()]),
+                 'edge [%s]' % ','.join(['%s="%s"' % (k,v) for (k,v)
+                                         in self.edge_defaults.items()])]
+        if self.body:
+            lines.append(self.body)
+        lines.append('/* Nodes */')
+        for node in self.nodes:
+            lines.append(node.to_dotfile())
+        lines.append('/* Edges */')
+        for edge in self.edges:
+            lines.append(edge.to_dotfile())
+        lines.append('}')
+
+        # Default dot input encoding is UTF-8
+        return u'\n'.join(lines).encode('utf-8')
+
+class DotGraphNode:
+    _next_id = 0
+    def __init__(self, label=None, html_label=None, **attribs):
+        if label is not None and html_label is not None:
+            raise ValueError('Use label or html_label, not both.')
+        if label is not None: attribs['label'] = label
+        self._html_label = html_label
+        self._attribs = attribs
+        self.id = self.__class__._next_id
+        self.__class__._next_id += 1
+        self.port = None
+
+    def __getitem__(self, attr):
+        return self._attribs[attr]
+
+    def __setitem__(self, attr, val):
+        if attr == 'html_label':
+            self._attribs.pop('label')
+            self._html_label = val
+        else:
+            if attr == 'label': self._html_label = None
+            self._attribs[attr] = val
+
+    def to_dotfile(self):
+        """
+        Return the dot commands that should be used to render this node.
+        """
+        attribs = ['%s="%s"' % (k,v) for (k,v) in self._attribs.items()
+                   if v is not None]
+        if self._html_label:
+            attribs.insert(0, 'label=<%s>' % (self._html_label,))
+        if attribs: attribs = ' [%s]' % (','.join(attribs))
+        return 'node%d%s' % (self.id, attribs)
+
+class DotGraphEdge:
+    def __init__(self, start, end, label=None, **attribs):
+        """
+        :type start: `DotGraphNode`
+        :type end: `DotGraphNode`
+        """
+        assert isinstance(start, DotGraphNode)
+        assert isinstance(end, DotGraphNode)
+        if label is not None: attribs['label'] = label
+        self.start = start       #: :type: `DotGraphNode`
+        self.end = end           #: :type: `DotGraphNode`
+        self._attribs = attribs
+
+    def __getitem__(self, attr):
+        return self._attribs[attr]
+
+    def __setitem__(self, attr, val):
+        self._attribs[attr] = val
+
+    def to_dotfile(self):
+        """
+        Return the dot commands that should be used to render this edge.
+        """
+        # Set head & tail ports, if the nodes have preferred ports.
+        attribs = self._attribs.copy()
+        if (self.start.port is not None and 'headport' not in attribs):
+            attribs['headport'] = self.start.port
+        if (self.end.port is not None and 'tailport' not in attribs):
+            attribs['tailport'] = self.end.port
+        # Convert attribs to a string
+        attribs = ','.join(['%s="%s"' % (k,v) for (k,v) in attribs.items()
+                            if v is not None])
+        if attribs: attribs = ' [%s]' % attribs
+        # Return the dotfile edge.
+        return 'node%d -> node%d%s' % (self.start.id, self.end.id, attribs)
+
+######################################################################
+#{ Specialized Nodes for UML Graphs
+######################################################################
+
+class DotGraphUmlClassNode(DotGraphNode):
+    """
+    A specialized dot graph node used to display `ClassDoc`\s using
+    UML notation.  The node is rendered as a table with three cells:
+    the top cell contains the class name; the middle cell contains a
+    list of attributes; and the bottom cell contains a list of
+    operations::
+
+         +-------------+
+         |  ClassName  |
+         +-------------+
+         | x: int      |
+         |     ...     |
+         +-------------+
+         | f(self, x)  |
+         |     ...     |
+         +-------------+
+
+    `DotGraphUmlClassNode`\s may be *collapsed*, in which case they are
+    drawn as a simple box containing the class name::
+    
+         +-------------+
+         |  ClassName  |
+         +-------------+
+         
+    Attributes with types corresponding to documented classes can
+    optionally be converted into edges, using `link_attributes()`.
+
+    :todo: Add more options?
+      - show/hide operation signature
+      - show/hide operation signature types
+      - show/hide operation signature return type
+      - show/hide attribute types
+      - use qualifiers
+    """
+
+    def __init__(self, class_doc, linker, context, collapsed=False,
+                 bgcolor=CLASS_BG, **options):
+        """
+        Create a new `DotGraphUmlClassNode` based on the class
+        `class_doc`.
+
+        :Parameters:
+            `linker` : `markup.DocstringLinker`
+                Used to look up URLs for classes.
+            `context` : `APIDoc`
+                The context in which this node will be drawn; dotted
+                names will be contextualized to this context.
+            `collapsed` : ``bool``
+                If true, then display this node as a simple box.
+            `bgcolor` : ```str```
+                The background color for this node.
+            `options` : ``dict``
+                A set of options used to control how the node should
+                be displayed.
+
+        :Keywords:
+          - `show_private_vars`: If false, then private variables
+            are filtered out of the attributes & operations lists.
+            (Default: *False*)
+          - `show_magic_vars`: If false, then magic variables
+            (such as ``__init__`` and ``__add__``) are filtered out of
+            the attributes & operations lists. (Default: *True*)
+          - `show_inherited_vars`: If false, then inherited variables
+            are filtered out of the attributes & operations lists.
+            (Default: *False*)
+          - `max_attributes`: The maximum number of attributes that
+            should be listed in the attribute box.  If the class has
+            more than this number of attributes, some will be
+            ellided.  Ellipsis is marked with ``'...'``.
+          - `max_operations`: The maximum number of operations that
+            should be listed in the operation box.
+          - `add_nodes_for_linked_attributes`: If true, then
+            `link_attributes()` will create new a collapsed node for
+            the types of a linked attributes if no node yet exists for
+            that type.
+        """
+        if not isinstance(class_doc, ClassDoc):
+            raise TypeError('Expected a ClassDoc as 1st argument')
+        
+        self.class_doc = class_doc
+        """The class represented by this node."""
+        
+        self.linker = linker
+        """Used to look up URLs for classes."""
+        
+        self.context = context
+        """The context in which the node will be drawn."""
+        
+        self.bgcolor = bgcolor
+        """The background color of the node."""
+        
+        self.options = options
+        """Options used to control how the node is displayed."""
+
+        self.collapsed = collapsed
+        """If true, then draw this node as a simple box."""
+        
+        self.attributes = []
+        """The list of VariableDocs for attributes"""
+        
+        self.operations = []
+        """The list of VariableDocs for operations"""
+        
+        self.qualifiers = []
+        """List of (key_label, port) tuples."""
+
+        self.edges = []
+        """List of edges used to represent this node's attributes.
+        These should not be added to the `DotGraph`; this node will
+        generate their dotfile code directly."""
+
+        # Initialize operations & attributes lists.
+        show_private = options.get('show_private_vars', False)
+        show_magic = options.get('show_magic_vars', True)
+        show_inherited = options.get('show_inherited_vars', False)
+        for var in class_doc.sorted_variables:
+            name = var.canonical_name[-1]
+            if ((not show_private and var.is_public == False) or
+                (not show_magic and re.match('__\w+__$', name)) or
+                (not show_inherited and var.container != class_doc)):
+                pass
+            elif isinstance(var.value, RoutineDoc):
+                self.operations.append(var)
+            else:
+                self.attributes.append(var)
+
+        # Initialize our dot node settings.
+        tooltip = self._summary(class_doc)
+        if tooltip:
+            # dot chokes on a \n in the attribute...
+            tooltip = " ".join(tooltip.split())
+        else:
+            tooltip = class_doc.canonical_name
+        DotGraphNode.__init__(self, tooltip=tooltip,
+                              width=0, height=0, shape='plaintext',
+                              href=linker.url_for(class_doc) or NOOP_URL)
+
+    #/////////////////////////////////////////////////////////////////
+    #{ Attribute Linking
+    #/////////////////////////////////////////////////////////////////
+    
+    SIMPLE_TYPE_RE = re.compile(
+        r'^([\w\.]+)$')
+    """A regular expression that matches descriptions of simple types."""
+    
+    COLLECTION_TYPE_RE = re.compile(
+        r'^(list|set|sequence|tuple|collection) of ([\w\.]+)$')
+    """A regular expression that matches descriptions of collection types."""
+
+    MAPPING_TYPE_RE = re.compile(
+        r'^(dict|dictionary|map|mapping) from ([\w\.]+) to ([\w\.]+)$')
+    """A regular expression that matches descriptions of mapping types."""
+
+    MAPPING_TO_COLLECTION_TYPE_RE = re.compile(
+        r'^(dict|dictionary|map|mapping) from ([\w\.]+) to '
+        r'(list|set|sequence|tuple|collection) of ([\w\.]+)$')
+    """A regular expression that matches descriptions of mapping types
+    whose value type is a collection."""
+
+    OPTIONAL_TYPE_RE = re.compile(
+        r'^(None or|optional) ([\w\.]+)$|^([\w\.]+) or None$')
+    """A regular expression that matches descriptions of optional types."""
+    
+    def link_attributes(self, nodes):
+        """
+        Convert any attributes with type descriptions corresponding to
+        documented classes to edges.  The following type descriptions
+        are currently handled:
+
+          - Dotted names: Create an attribute edge to the named type,
+            labelled with the variable name.
+          - Collections: Create an attribute edge to the named type,
+            labelled with the variable name, and marked with '*' at the
+            type end of the edge.
+          - Mappings: Create an attribute edge to the named type,
+            labelled with the variable name, connected to the class by
+            a qualifier box that contains the key type description.
+          - Optional: Create an attribute edge to the named type,
+            labelled with the variable name, and marked with '0..1' at
+            the type end of the edge.
+
+        The edges created by `link_attributes()` are handled internally
+        by `DotGraphUmlClassNode`; they should *not* be added directly
+        to the `DotGraph`.
+
+        :param nodes: A dictionary mapping from `ClassDoc`\s to
+            `DotGraphUmlClassNode`\s, used to look up the nodes for
+            attribute types.  If the ``add_nodes_for_linked_attributes``
+            option is used, then new nodes will be added to this
+            dictionary for any types that are not already listed.
+            These added nodes must be added to the `DotGraph`.
+        """
+        # Try to convert each attribute var into a graph edge.  If
+        # _link_attribute returns true, then it succeeded, so remove
+        # that var from our attribute list; otherwise, leave that var
+        # in our attribute list.
+        self.attributes = [var for var in self.attributes
+                           if not self._link_attribute(var, nodes)]
+
+    def _link_attribute(self, var, nodes):
+        """
+        Helper for `link_attributes()`: try to convert the attribute
+        variable `var` into an edge, and add that edge to
+        `self.edges`.  Return ``True`` iff the variable was
+        successfully converted to an edge (in which case, it should be
+        removed from the attributes list).
+        """
+        type_descr = self._type_descr(var) or self._type_descr(var.value)
+        
+        # Simple type.
+        m = self.SIMPLE_TYPE_RE.match(type_descr)
+        if m and self._add_attribute_edge(var, nodes, m.group(1)):
+            return True
+
+        # Collection type.
+        m = self.COLLECTION_TYPE_RE.match(type_descr)
+        if m and self._add_attribute_edge(var, nodes, m.group(2),
+                                          headlabel='*'):
+            return True
+
+        # Optional type.
+        m = self.OPTIONAL_TYPE_RE.match(type_descr)
+        if m and self._add_attribute_edge(var, nodes, m.group(2) or m.group(3),
+                                          headlabel='0..1'):
+            return True
+                
+        # Mapping type.
+        m = self.MAPPING_TYPE_RE.match(type_descr)
+        if m:
+            port = 'qualifier_%s' % var.name
+            if self._add_attribute_edge(var, nodes, m.group(3),
+                                        tailport='%s:e' % port):
+                self.qualifiers.append( (m.group(2), port) )
+                return True
+
+        # Mapping to collection type.
+        m = self.MAPPING_TO_COLLECTION_TYPE_RE.match(type_descr)
+        if m:
+            port = 'qualifier_%s' % var.name
+            if self._add_attribute_edge(var, nodes, m.group(4), headlabel='*', 
+                                        tailport='%s:e' % port):
+                self.qualifiers.append( (m.group(2), port) )
+                return True
+
+        # We were unable to link this attribute.
+        return False
+
+    def _add_attribute_edge(self, var, nodes, type_str, **attribs):
+        """
+        Helper for `link_attributes()`: try to add an edge for the
+        given attribute variable `var`.  Return ``True`` if
+        successful.
+        """
+        # Use the type string to look up a corresponding ValueDoc.
+        type_doc = self.linker.docindex.find(type_str, var)
+        if not type_doc: return False
+
+        # Make sure the type is a class.
+        if not isinstance(type_doc, ClassDoc): return False
+
+        # Get the type ValueDoc's node.  If it doesn't have one (and
+        # add_nodes_for_linked_attributes=True), then create it.
+        type_node = nodes.get(type_doc)
+        if not type_node:
+            if self.options.get('add_nodes_for_linked_attributes', True):
+                type_node = DotGraphUmlClassNode(type_doc, self.linker,
+                                                 self.context, collapsed=True)
+                nodes[type_doc] = type_node
+            else:
+                return False
+
+        # Add an edge from self to the target type node.
+        # [xx] should I set constraint=false here?
+        attribs.setdefault('headport', 'body')
+        attribs.setdefault('tailport', 'body')
+        url = self.linker.url_for(var) or NOOP_URL
+        self.edges.append(DotGraphEdge(self, type_node, label=var.name,
+                        arrowhead='open', href=url,
+                        tooltip=var.canonical_name, labeldistance=1.5,
+                        **attribs))
+        return True
+                           
+    #/////////////////////////////////////////////////////////////////
+    #{ Helper Methods
+    #/////////////////////////////////////////////////////////////////
+    def _summary(self, api_doc):
+        """Return a plaintext summary for `api_doc`"""
+        if not isinstance(api_doc, APIDoc): return ''
+        if api_doc.summary in (None, UNKNOWN): return ''
+        summary = api_doc.summary.to_plaintext(None).strip()
+        return plaintext_to_html(summary)
+
+    _summary = classmethod(_summary)
+
+    def _type_descr(self, api_doc):
+        """Return a plaintext type description for `api_doc`"""
+        if not hasattr(api_doc, 'type_descr'): return ''
+        if api_doc.type_descr in (None, UNKNOWN): return ''
+        type_descr = api_doc.type_descr.to_plaintext(self.linker).strip()
+        return plaintext_to_html(type_descr)
+
+    def _tooltip(self, var_doc):
+        """Return a tooltip for `var_doc`."""
+        return (self._summary(var_doc) or
+                self._summary(var_doc.value) or
+                var_doc.canonical_name)
+    
+    #/////////////////////////////////////////////////////////////////
+    #{ Rendering
+    #/////////////////////////////////////////////////////////////////
+    
+    def _attribute_cell(self, var_doc):
+        # Construct the label
+        label = var_doc.name
+        type_descr = (self._type_descr(var_doc) or
+                      self._type_descr(var_doc.value))
+        if type_descr: label += ': %s' % type_descr
+        # Get the URL
+        url = self.linker.url_for(var_doc) or NOOP_URL
+        # Construct & return the pseudo-html code
+        return self._ATTRIBUTE_CELL % (url, self._tooltip(var_doc), label)
+
+    def _operation_cell(self, var_doc):
+        """
+        :todo: do 'word wrapping' on the signature, by starting a new
+               row in the table, if necessary.  How to indent the new
+               line?  Maybe use align=right?  I don't think dot has a
+               &nbsp;.
+        :todo: Optionally add return type info?
+        """
+        # Construct the label (aka function signature)
+        func_doc = var_doc.value
+        args = [self._operation_arg(n, d, func_doc) for (n, d)
+                in zip(func_doc.posargs, func_doc.posarg_defaults)]
+        args = [plaintext_to_html(arg) for arg in args]
+        if func_doc.vararg: args.append('*'+func_doc.vararg)
+        if func_doc.kwarg: args.append('**'+func_doc.kwarg)
+        label = '%s(%s)' % (var_doc.name, ', '.join(args))
+        # Get the URL
+        url = self.linker.url_for(var_doc) or NOOP_URL
+        # Construct & return the pseudo-html code
+        return self._OPERATION_CELL % (url, self._tooltip(var_doc), label)
+
+    def _operation_arg(self, name, default, func_doc):
+        """
+        :todo: Handle tuple args better
+        :todo: Optionally add type info?
+        """
+        if default is None:
+            return '%s' % name
+        else:
+            pyval_repr = default.summary_pyval_repr().to_plaintext(None)
+            return '%s=%s' % (name, pyval_repr)
+
+    def _qualifier_cell(self, key_label, port):
+        return self._QUALIFIER_CELL  % (port, self.bgcolor, key_label)
+
+    #: args: (url, tooltip, label)
+    _ATTRIBUTE_CELL = '''
+    <TR><TD ALIGN="LEFT" HREF="%s" TOOLTIP="%s">%s</TD></TR>
+    '''
+
+    #: args: (url, tooltip, label)
+    _OPERATION_CELL = '''
+    <TR><TD ALIGN="LEFT" HREF="%s" TOOLTIP="%s">%s</TD></TR>
+    '''
+
+    #: args: (port, bgcolor, label)
+    _QUALIFIER_CELL = '''
+    <TR><TD VALIGN="BOTTOM" PORT="%s" BGCOLOR="%s" BORDER="1">%s</TD></TR>
+    '''
+
+    _QUALIFIER_DIV = '''
+    <TR><TD VALIGN="BOTTOM" HEIGHT="10" WIDTH="10" FIXEDSIZE="TRUE"></TD></TR>
+    '''
+    
+    #: Args: (rowspan, bgcolor, classname, attributes, operations, qualifiers)
+    _LABEL = '''
+    <TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0" CELLPADDING="0">
+      <TR><TD ROWSPAN="%s">
+        <TABLE BORDER="0" CELLBORDER="1" CELLSPACING="0"
+               CELLPADDING="0" PORT="body" BGCOLOR="%s">
+          <TR><TD>%s</TD></TR>
+          <TR><TD><TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0">
+            %s</TABLE></TD></TR>
+          <TR><TD><TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0">
+            %s</TABLE></TD></TR>
+        </TABLE>
+      </TD></TR>
+      %s
+    </TABLE>'''
+
+    _COLLAPSED_LABEL = '''
+    <TABLE CELLBORDER="0" BGCOLOR="%s" PORT="body">
+      <TR><TD>%s</TD></TR>
+    </TABLE>'''
+
+    def _get_html_label(self):
+        # Get the class name & contextualize it.
+        classname = self.class_doc.canonical_name
+        classname = classname.contextualize(self.context.canonical_name)
+        
+        # If we're collapsed, display the node as a single box.
+        if self.collapsed:
+            return self._COLLAPSED_LABEL % (self.bgcolor, classname)
+        
+        # Construct the attribute list.  (If it's too long, truncate)
+        attrib_cells = [self._attribute_cell(a) for a in self.attributes]
+        max_attributes = self.options.get('max_attributes', 15)
+        if len(attrib_cells) == 0:
+            attrib_cells = ['<TR><TD></TD></TR>']
+        elif len(attrib_cells) > max_attributes:
+            attrib_cells[max_attributes-2:-1] = ['<TR><TD>...</TD></TR>']
+        attributes = ''.join(attrib_cells)
+                      
+        # Construct the operation list.  (If it's too long, truncate)
+        oper_cells = [self._operation_cell(a) for a in self.operations]
+        max_operations = self.options.get('max_operations', 15)
+        if len(oper_cells) == 0:
+            oper_cells = ['<TR><TD></TD></TR>']
+        elif len(oper_cells) > max_operations:
+            oper_cells[max_operations-2:-1] = ['<TR><TD>...</TD></TR>']
+        operations = ''.join(oper_cells)
+
+        # Construct the qualifier list & determine the rowspan.
+        if self.qualifiers:
+            rowspan = len(self.qualifiers)*2+2
+            div = self._QUALIFIER_DIV
+            qualifiers = div+div.join([self._qualifier_cell(l,p) for
+                                     (l,p) in self.qualifiers])+div
+        else:
+            rowspan = 1
+            qualifiers = ''
+
+        # Put it all together.
+        return self._LABEL % (rowspan, self.bgcolor, classname,
+                              attributes, operations, qualifiers)
+
+    def to_dotfile(self):
+        attribs = ['%s="%s"' % (k,v) for (k,v) in self._attribs.items()]
+        attribs.append('label=<%s>' % self._get_html_label())
+        s = 'node%d%s' % (self.id, ' [%s]' % (','.join(attribs)))
+        if not self.collapsed:
+            for edge in self.edges:
+                s += '\n' + edge.to_dotfile()
+        return s
+
+class DotGraphUmlModuleNode(DotGraphNode):
+    """
+    A specialized dot grah node used to display `ModuleDoc`\s using
+    UML notation.  Simple module nodes look like::
+
+        .----.
+        +------------+
+        | modulename |
+        +------------+
+
+    Packages nodes are drawn with their modules & subpackages nested
+    inside::
+        
+        .----.
+        +----------------------------------------+
+        | packagename                            |
+        |                                        |
+        |  .----.       .----.       .----.      |
+        |  +---------+  +---------+  +---------+ |
+        |  | module1 |  | module2 |  | module3 | |
+        |  +---------+  +---------+  +---------+ |
+        |                                        |
+        +----------------------------------------+
+
+    """
+    def __init__(self, module_doc, linker, context, collapsed=False,
+                 excluded_submodules=(), **options):
+        self.module_doc = module_doc
+        self.linker = linker
+        self.context = context
+        self.collapsed = collapsed
+        self.options = options
+        self.excluded_submodules = excluded_submodules
+        DotGraphNode.__init__(self, shape='plaintext',
+                              href=linker.url_for(module_doc) or NOOP_URL,
+                              tooltip=module_doc.canonical_name)
+
+    #: Expects: (color, color, url, tooltip, body)
+    _MODULE_LABEL = ''' 
+    <TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0" ALIGN="LEFT">
+    <TR><TD ALIGN="LEFT" VALIGN="BOTTOM" HEIGHT="8" WIDTH="16"
+            FIXEDSIZE="true" BGCOLOR="%s" BORDER="1" PORT="tab"></TD></TR>
+    <TR><TD ALIGN="LEFT" VALIGN="TOP" BGCOLOR="%s" BORDER="1" WIDTH="20"
+            PORT="body" HREF="%s" TOOLTIP="%s">%s</TD></TR>
+    </TABLE>'''
+
+    #: Expects: (name, body_rows)
+    _NESTED_BODY = '''
+    <TABLE BORDER="0" CELLBORDER="0" CELLPADDING="0" CELLSPACING="0">
+    <TR><TD ALIGN="LEFT">%s</TD></TR>
+    %s
+    </TABLE>'''
+
+    #: Expects: (cells,)
+    _NESTED_BODY_ROW = '''
+    <TR><TD>
+      <TABLE BORDER="0" CELLBORDER="0"><TR>%s</TR></TABLE>
+    </TD></TR>'''
+    
+    def _get_html_label(self, package):
+        """
+        :Return: (label, depth, width) where:
+        
+          - ``label`` is the HTML label
+          - ``depth`` is the depth of the package tree (for coloring)
+          - ``width`` is the max width of the HTML label, roughly in
+            units of characters.
+        """
+        MAX_ROW_WIDTH = 80 # unit is roughly characters.
+        pkg_name = package.canonical_name
+        pkg_url = self.linker.url_for(package) or NOOP_URL
+        
+        if (not package.is_package or len(package.submodules) == 0 or
+            self.collapsed):
+            pkg_color = self._color(package, 1)
+            label = self._MODULE_LABEL % (pkg_color, pkg_color,
+                                          pkg_url, pkg_name, pkg_name[-1])
+            return (label, 1, len(pkg_name[-1])+3)
+                
+        # Get the label for each submodule, and divide them into rows.
+        row_list = ['']
+        row_width = 0
+        max_depth = 0
+        max_row_width = len(pkg_name[-1])+3
+        for submodule in package.submodules:
+            if submodule in self.excluded_submodules: continue
+            # Get the submodule's label.
+            label, depth, width = self._get_html_label(submodule)
+            # Check if we should start a new row.
+            if row_width > 0 and width+row_width > MAX_ROW_WIDTH:
+                row_list.append('')
+                row_width = 0
+            # Add the submodule's label to the row.
+            row_width += width
+            row_list[-1] += '<TD ALIGN="LEFT">%s</TD>' % label
+            # Update our max's.
+            max_depth = max(depth, max_depth)
+            max_row_width = max(row_width, max_row_width)
+
+        # Figure out which color to use.
+        pkg_color = self._color(package, depth+1)
+        
+        # Assemble & return the label.
+        rows = ''.join([self._NESTED_BODY_ROW % r for r in row_list])
+        body = self._NESTED_BODY % (pkg_name, rows)
+        label = self._MODULE_LABEL % (pkg_color, pkg_color,
+                                      pkg_url, pkg_name, body)
+        return label, max_depth+1, max_row_width
+
+    _COLOR_DIFF = 24
+    def _color(self, package, depth):
+        if package == self.context: return SELECTED_BG
+        else: 
+            # Parse the base color.
+            if re.match(MODULE_BG, 'r#[0-9a-fA-F]{6}$'):
+                base = int(MODULE_BG[1:], 16)
+            else:
+                base = int('d8e8ff', 16)
+            red = (base & 0xff0000) >> 16
+            green = (base & 0x00ff00) >> 8
+            blue = (base & 0x0000ff)
+            # Make it darker with each level of depth. (but not *too*
+            # dark -- package name needs to be readable)
+            red = max(64, red-(depth-1)*self._COLOR_DIFF)
+            green = max(64, green-(depth-1)*self._COLOR_DIFF)
+            blue = max(64, blue-(depth-1)*self._COLOR_DIFF)
+            # Convert it back to a color string
+            return '#%06x' % ((red<<16)+(green<<8)+blue)
+        
+    def to_dotfile(self):
+        attribs = ['%s="%s"' % (k,v) for (k,v) in self._attribs.items()]
+        label, depth, width = self._get_html_label(self.module_doc)
+        attribs.append('label=<%s>' % label)
+        return 'node%d%s' % (self.id, ' [%s]' % (','.join(attribs)))
+
+
+    
+######################################################################
+#{ Graph Generation Functions
+######################################################################
+
+def package_tree_graph(packages, linker, context=None, **options):
+    """
+    Return a `DotGraph` that graphically displays the package
+    hierarchies for the given packages.
+    """
+    if options.get('style', 'uml') == 'uml': # default to uml style?
+        if get_dot_version() >= [2]:
+            return uml_package_tree_graph(packages, linker, context,
+                                             **options)
+        elif 'style' in options:
+            log.warning('UML style package trees require dot version 2.0+')
+
+    graph = DotGraph('Package Tree for %s' % name_list(packages, context),
+                     body='ranksep=.3\n;nodesep=.1\n',
+                     edge_defaults={'dir':'none'})
+    
+    # Options
+    if options.get('dir', 'TB') != 'TB': # default: top-to-bottom
+        graph.body += 'rankdir=%s\n' % options.get('dir', 'TB')
+
+    # Get a list of all modules in the package.
+    queue = list(packages)
+    modules = set(packages)
+    for module in queue:
+        queue.extend(module.submodules)
+        modules.update(module.submodules)
+
+    # Add a node for each module.
+    nodes = add_valdoc_nodes(graph, modules, linker, context)
+
+    # Add an edge for each package/submodule relationship.
+    for module in modules:
+        for submodule in module.submodules:
+            graph.edges.append(DotGraphEdge(nodes[module], nodes[submodule],
+                                            headport='tab'))
+
+    return graph
+
+def uml_package_tree_graph(packages, linker, context=None, **options):
+    """
+    Return a `DotGraph` that graphically displays the package
+    hierarchies for the given packages as a nested set of UML
+    symbols.
+    """
+    graph = DotGraph('Package Tree for %s' % name_list(packages, context))
+    # Remove any packages whose containers are also in the list.
+    root_packages = []
+    for package1 in packages:
+        for package2 in packages:
+            if (package1 is not package2 and
+                package2.canonical_name.dominates(package1.canonical_name)):
+                break
+        else:
+            root_packages.append(package1)
+    # If the context is a variable, then get its value.
+    if isinstance(context, VariableDoc) and context.value is not UNKNOWN:
+        context = context.value
+    # Return a graph with one node for each root package.
+    for package in root_packages:
+        graph.nodes.append(DotGraphUmlModuleNode(package, linker, context))
+    return graph
+
+######################################################################
+def class_tree_graph(bases, linker, context=None, **options):
+    """
+    Return a `DotGraph` that graphically displays the class
+    hierarchy for the given classes.  Options:
+
+      - exclude
+      - dir: LR|RL|BT requests a left-to-right, right-to-left, or
+        bottom-to- top, drawing.  (corresponds to the dot option
+        'rankdir'
+    """
+    if isinstance(bases, ClassDoc): bases = [bases]
+    graph = DotGraph('Class Hierarchy for %s' % name_list(bases, context),
+                     body='ranksep=0.3\n',
+                     edge_defaults={'sametail':True, 'dir':'none'})
+
+    # Options
+    if options.get('dir', 'TB') != 'TB': # default: top-down
+        graph.body += 'rankdir=%s\n' % options.get('dir', 'TB')
+    exclude = options.get('exclude', ())
+
+    # Find all superclasses & subclasses of the given classes.
+    classes = set(bases)
+    queue = list(bases)
+    for cls in queue:
+        if isinstance(cls, ClassDoc):
+            if cls.subclasses not in (None, UNKNOWN):
+                subclasses = cls.subclasses
+                if exclude:
+                    subclasses = [d for d in subclasses if d not in exclude]
+                queue.extend(subclasses)
+                classes.update(subclasses)
+    queue = list(bases)
+    for cls in queue:
+        if isinstance(cls, ClassDoc):
+            if cls.bases not in (None, UNKNOWN):
+                bases = cls.bases
+                if exclude:
+                    bases = [d for d in bases if d not in exclude]
+                queue.extend(bases)
+                classes.update(bases)
+
+    # Add a node for each cls.
+    classes = [d for d in classes if isinstance(d, ClassDoc)
+               if d.pyval is not object]
+    nodes = add_valdoc_nodes(graph, classes, linker, context)
+
+    # Add an edge for each package/subclass relationship.
+    edges = set()
+    for cls in classes:
+        for subcls in cls.subclasses:
+            if cls in nodes and subcls in nodes:
+                edges.add((nodes[cls], nodes[subcls]))
+    graph.edges = [DotGraphEdge(src,dst) for (src,dst) in edges]
+
+    return graph
+
+######################################################################
+def uml_class_tree_graph(class_doc, linker, context=None, **options):
+    """
+    Return a `DotGraph` that graphically displays the class hierarchy
+    for the given class, using UML notation.  Options:
+
+      - max_attributes
+      - max_operations
+      - show_private_vars
+      - show_magic_vars
+      - link_attributes
+    """
+    nodes = {} # ClassDoc -> DotGraphUmlClassNode
+    exclude = options.get('exclude', ())
+        
+    # Create nodes for class_doc and all its bases.
+    for cls in class_doc.mro():
+        if cls.pyval is object: continue # don't include `object`.
+        if cls in exclude: break # stop if we get to an excluded class.
+        if cls == class_doc: color = SELECTED_BG
+        else: color = BASECLASS_BG
+        nodes[cls] = DotGraphUmlClassNode(cls, linker, context,
+                                          show_inherited_vars=False,
+                                          collapsed=False, bgcolor=color)
+
+    # Create nodes for all class_doc's subclasses.
+    queue = [class_doc]
+    for cls in queue:
+        if (isinstance(cls, ClassDoc) and
+            cls.subclasses not in (None, UNKNOWN)):
+            for subcls in cls.subclasses:
+                subcls_name = subcls.canonical_name[-1]
+                if subcls not in nodes and subcls not in exclude:
+                    queue.append(subcls)
+                    nodes[subcls] = DotGraphUmlClassNode(
+                        subcls, linker, context, collapsed=True,
+                        bgcolor=SUBCLASS_BG)
+                    
+    # Only show variables in the class where they're defined for
+    # *class_doc*.
+    mro = class_doc.mro()
+    for name, var in class_doc.variables.items():
+        i = mro.index(var.container)
+        for base in mro[i+1:]:
+            if base.pyval is object: continue # don't include `object`.
+            overridden_var = base.variables.get(name)
+            if overridden_var and overridden_var.container == base:
+                try:
+                    if isinstance(overridden_var.value, RoutineDoc):
+                        nodes[base].operations.remove(overridden_var)
+                    else:
+                        nodes[base].attributes.remove(overridden_var)
+                except ValueError:
+                    pass # var is filtered (eg private or magic)
+
+    # Keep track of which nodes are part of the inheritance graph
+    # (since link_attributes might add new nodes)
+    inheritance_nodes = set(nodes.values())
+        
+    # Turn attributes into links.
+    if options.get('link_attributes', True):
+        for node in nodes.values():
+            node.link_attributes(nodes)
+            # Make sure that none of the new attribute edges break the
+            # rank ordering assigned by inheritance.
+            for edge in node.edges:
+                if edge.end in inheritance_nodes:
+                    edge['constraint'] = 'False'
+                
+    # Construct the graph.
+    graph = DotGraph('UML class diagram for %s' % class_doc.canonical_name,
+                     body='ranksep=.2\n;nodesep=.3\n')
+    graph.nodes = nodes.values()
+    
+    # Add inheritance edges.
+    for node in inheritance_nodes:
+        for base in node.class_doc.bases:
+            if base in nodes:
+                graph.edges.append(DotGraphEdge(nodes[base], node,
+                              dir='back', arrowtail='empty',
+                              headport='body', tailport='body',
+                              color=INH_LINK_COLOR, weight=100,
+                              style='bold'))
+
+    # And we're done!
+    return graph
+
+######################################################################
+def import_graph(modules, docindex, linker, context=None, **options):
+    graph = DotGraph('Import Graph', body='ranksep=.3\n;nodesep=.3\n')
+
+    # Options
+    if options.get('dir', 'RL') != 'TB': # default: right-to-left.
+        graph.body += 'rankdir=%s\n' % options.get('dir', 'RL')
+
+    # Add a node for each module.
+    nodes = add_valdoc_nodes(graph, modules, linker, context)
+
+    # Edges.
+    edges = set()
+    for dst in modules:
+        if dst.imports in (None, UNKNOWN): continue
+        for var_name in dst.imports:
+            for i in range(len(var_name), 0, -1):
+                val_doc = docindex.find(var_name[:i], context)
+                if isinstance(val_doc, ModuleDoc):
+                    if val_doc in nodes and dst in nodes:
+                        edges.add((nodes[val_doc], nodes[dst]))
+                    break
+    graph.edges = [DotGraphEdge(src,dst) for (src,dst) in edges]
+
+    return graph
+
+######################################################################
+def call_graph(api_docs, docindex, linker, context=None, **options):
+    """
+    :param options:
+        - ``dir``: rankdir for the graph.  (default=LR)
+        - ``add_callers``: also include callers for any of the
+          routines in ``api_docs``.  (default=False)
+        - ``add_callees``: also include callees for any of the
+          routines in ``api_docs``.  (default=False)
+    :todo: Add an ``exclude`` option?
+    """
+    if docindex.callers is None:
+        log.warning("No profiling information for call graph!")
+        return DotGraph('Call Graph') # return None instead?
+
+    if isinstance(context, VariableDoc):
+        context = context.value
+
+    # Get the set of requested functions.
+    functions = []
+    for api_doc in api_docs:
+        # If it's a variable, get its value.
+        if isinstance(api_doc, VariableDoc):
+            api_doc = api_doc.value
+        # Add the value to the functions list.
+        if isinstance(api_doc, RoutineDoc):
+            functions.append(api_doc)
+        elif isinstance(api_doc, NamespaceDoc):
+            for vardoc in api_doc.variables.values():
+                if isinstance(vardoc.value, RoutineDoc):
+                    functions.append(vardoc.value)
+
+    # Filter out functions with no callers/callees?
+    # [xx] this isnt' quite right, esp if add_callers or add_callees
+    # options are fales.
+    functions = [f for f in functions if
+                 (f in docindex.callers) or (f in docindex.callees)]
+        
+    # Add any callers/callees of the selected functions
+    func_set = set(functions)
+    if options.get('add_callers', False) or options.get('add_callees', False):
+        for func_doc in functions:
+            if options.get('add_callers', False):
+                func_set.update(docindex.callers.get(func_doc, ()))
+            if options.get('add_callees', False):
+                func_set.update(docindex.callees.get(func_doc, ()))
+
+    graph = DotGraph('Call Graph for %s' % name_list(api_docs, context),
+                     node_defaults={'shape':'box', 'width': 0, 'height': 0})
+    
+    # Options
+    if options.get('dir', 'LR') != 'TB': # default: left-to-right
+        graph.body += 'rankdir=%s\n' % options.get('dir', 'LR')
+
+    nodes = add_valdoc_nodes(graph, func_set, linker, context)
+    
+    # Find the edges.
+    edges = set()
+    for func_doc in functions:
+        for caller in docindex.callers.get(func_doc, ()):
+            if caller in nodes:
+                edges.add( (nodes[caller], nodes[func_doc]) )
+        for callee in docindex.callees.get(func_doc, ()):
+            if callee in nodes:
+                edges.add( (nodes[func_doc], nodes[callee]) )
+    graph.edges = [DotGraphEdge(src,dst) for (src,dst) in edges]
+    
+    return graph
+
+######################################################################
+#{ Dot Version
+######################################################################
+
+_dot_version = None
+_DOT_VERSION_RE = re.compile(r'dot version ([\d\.]+)')
+def get_dot_version():
+    global _dot_version
+    if _dot_version is None:
+        try:
+            out, err = run_subprocess([DOT_COMMAND, '-V'])
+            version_info = err or out
+            m = _DOT_VERSION_RE.match(version_info)
+            if m:
+                _dot_version = [int(x) for x in m.group(1).split('.')]
+            else:
+                _dot_version = (0,)
+        except OSError, e:
+            _dot_version = (0,)
+        log.info('Detected dot version %s' % _dot_version)
+    return _dot_version
+
+######################################################################
+#{ Helper Functions
+######################################################################
+
+def add_valdoc_nodes(graph, val_docs, linker, context):
+    """
+    :todo: Use different node styles for different subclasses of APIDoc
+    """
+    nodes = {}
+    val_docs = sorted(val_docs, key=lambda d:d.canonical_name)
+    for i, val_doc in enumerate(val_docs):
+        label = val_doc.canonical_name.contextualize(context.canonical_name)
+        node = nodes[val_doc] = DotGraphNode(label)
+        graph.nodes.append(node)
+        specialize_valdoc_node(node, val_doc, context, linker.url_for(val_doc))
+    return nodes
+
+NOOP_URL = 'javascript:void(0);'
+MODULE_NODE_HTML = '''
+  <TABLE BORDER="0" CELLBORDER="0" CELLSPACING="0"
+         CELLPADDING="0" PORT="table" ALIGN="LEFT">
+  <TR><TD ALIGN="LEFT" VALIGN="BOTTOM" HEIGHT="8" WIDTH="16" FIXEDSIZE="true"
+          BGCOLOR="%s" BORDER="1" PORT="tab"></TD></TR>
+  <TR><TD ALIGN="LEFT" VALIGN="TOP" BGCOLOR="%s" BORDER="1"
+          PORT="body" HREF="%s" TOOLTIP="%s">%s</TD></TR>
+  </TABLE>'''.strip()
+
+def specialize_valdoc_node(node, val_doc, context, url):
+    """
+    Update the style attributes of `node` to reflext its type
+    and context.
+    """
+    # We can only use html-style nodes if dot_version>2.
+    dot_version = get_dot_version()
+    
+    # If val_doc or context is a variable, get its value.
+    if isinstance(val_doc, VariableDoc) and val_doc.value is not UNKNOWN:
+        val_doc = val_doc.value
+    if isinstance(context, VariableDoc) and context.value is not UNKNOWN:
+        context = context.value
+
+    # Set the URL.  (Do this even if it points to the page we're
+    # currently on; otherwise, the tooltip is ignored.)
+    node['href'] = url or NOOP_URL
+
+    if isinstance(val_doc, ModuleDoc) and dot_version >= [2]:
+        node['shape'] = 'plaintext'
+        if val_doc == context: color = SELECTED_BG
+        else: color = MODULE_BG
+        node['tooltip'] = node['label']
+        node['html_label'] = MODULE_NODE_HTML % (color, color, url,
+                                                 val_doc.canonical_name,
+                                                 node['label'])
+        node['width'] = node['height'] = 0
+        node.port = 'body'
+
+    elif isinstance(val_doc, RoutineDoc):
+        node['shape'] = 'box'
+        node['style'] = 'rounded'
+        node['width'] = 0
+        node['height'] = 0
+        node['label'] = '%s()' % node['label']
+        node['tooltip'] = node['label']
+        if val_doc == context:
+            node['fillcolor'] = SELECTED_BG
+            node['style'] = 'filled,rounded,bold'
+            
+    else:
+        node['shape'] = 'box' 
+        node['width'] = 0
+        node['height'] = 0
+        node['tooltip'] = node['label']
+        if val_doc == context:
+            node['fillcolor'] = SELECTED_BG
+            node['style'] = 'filled,bold'
+
+def name_list(api_docs, context=None):
+    if context is not None:
+        context = context.canonical_name
+    names = [str(d.canonical_name.contextualize(context)) for d in api_docs]
+    if len(names) == 0: return ''
+    if len(names) == 1: return '%s' % names[0]
+    elif len(names) == 2: return '%s and %s' % (names[0], names[1])
+    else:
+        return '%s, and %s' % (', '.join(names[:-1]), names[-1])
+