bee_python 0.0.1

data/tools/epydoc/docwriter/html.py

@@ -0,0 +1,3491 @@
+#
+# epydoc -- HTML output generator
+# Edward Loper
+#
+# Created [01/30/01 05:18 PM]
+# $Id: html.py,v 1.1 2009/11/26 13:20:44 casa Exp $
+#
+
+"""
+The HTML output generator for epydoc.  The main interface provided by
+this module is the L{HTMLWriter} class.
+
+@todo: Add a cache to L{HTMLWriter.url()}?
+"""
+__docformat__ = 'epytext en'
+
+import re, os, sys, codecs, sre_constants, pprint, base64
+import urllib
+import __builtin__
+from epydoc.apidoc import *
+import epydoc.docstringparser
+import time, epydoc, epydoc.markup, epydoc.markup.epytext
+from epydoc.docwriter.html_colorize import PythonSourceColorizer
+from epydoc.docwriter import html_colorize
+from epydoc.docwriter.html_css import STYLESHEETS
+from epydoc.docwriter.html_help import HTML_HELP
+from epydoc.docwriter.dotgraph import *
+from epydoc import log
+from epydoc.util import plaintext_to_html, is_src_filename
+from epydoc.compat import * # Backwards compatibility
+
+######################################################################
+## Template Compiler
+######################################################################
+# The compile_template() method defined in this section is used to
+# define several of HTMLWriter's methods.
+
+def compile_template(docstring, template_string,
+                     output_function='out', debug=epydoc.DEBUG):
+    """
+    Given a template string containing inline python source code,
+    return a python function that will fill in the template, and
+    output the result.  The signature for this function is taken from
+    the first line of C{docstring}.  Output is generated by making
+    repeated calls to the output function with the given name (which
+    is typically one of the function's parameters).
+
+    The templating language used by this function passes through all
+    text as-is, with three exceptions:
+
+      - If every line in the template string is indented by at least
+        M{x} spaces, then the first M{x} spaces are stripped from each
+        line.
+
+      - Any line that begins with '>>>' (with no indentation)
+        should contain python code, and will be inserted as-is into
+        the template-filling function.  If the line begins a control
+        block (such as 'if' or 'for'), then the control block will
+        be closed by the first '>>>'-marked line whose indentation is
+        less than or equal to the line's own indentation (including
+        lines that only contain comments.)
+
+      - In any other line, any expression between two '$' signs will
+        be evaluated and inserted into the line (using C{str()} to
+        convert the result to a string).
+
+    Here is a simple example:
+
+        >>> TEMPLATE = '''
+        ... <book>
+        ...   <title>$book.title$</title>
+        ...   <pages>$book.count_pages()$</pages>
+        ... >>> for chapter in book.chapters:
+        ...     <chaptername>$chapter.name$</chaptername>
+        ... >>> #endfor
+        ... </book>
+        >>> write_book = compile_template('write_book(out, book)', TEMPLATE)
+
+    @newfield acknowledgements: Acknowledgements
+    @acknowledgements: The syntax used by C{compile_template} is
+    loosely based on Cheetah.
+    """
+    # Extract signature from the docstring:
+    signature = docstring.lstrip().split('\n',1)[0].strip()
+    func_name = signature.split('(',1)[0].strip()
+
+    # Regexp to search for inline substitutions:
+    INLINE = re.compile(r'\$([^\$]+)\$')
+    # Regexp to search for python statements in the template:
+    COMMAND = re.compile(r'(^>>>.*)\n?', re.MULTILINE)
+
+    # Strip indentation from the template.
+    template_string = strip_indent(template_string)
+
+    # If we're debugging, then we'll store the generated function,
+    # so we can print it along with any tracebacks that depend on it.
+    if debug:
+        signature = re.sub(r'\)\s*$', ', __debug=__debug)', signature)
+
+    # Funciton declaration line
+    pysrc_lines = ['def %s:' % signature]
+    indents = [-1]
+
+    if debug:
+        pysrc_lines.append('    try:')
+        indents.append(-1)
+
+    commands = COMMAND.split(template_string.strip()+'\n')
+    for i, command in enumerate(commands):
+        if command == '': continue
+
+        # String literal segment:
+        if i%2 == 0:
+            pieces = INLINE.split(command)
+            for j, piece in enumerate(pieces):
+                if j%2 == 0:
+                    # String piece
+                    pysrc_lines.append('    '*len(indents)+
+                                 '%s(%r)' % (output_function, piece))
+                else:
+                    # Variable piece
+                    pysrc_lines.append('    '*len(indents)+
+                                 '%s(unicode(%s))' % (output_function, piece))
+
+        # Python command:
+        else:
+            srcline = command[3:].lstrip()
+            # Update indentation
+            indent = len(command)-len(srcline)
+            while indent <= indents[-1]: indents.pop()
+            # Add on the line.
+            srcline = srcline.rstrip()
+            pysrc_lines.append('    '*len(indents)+srcline)
+            if srcline.endswith(':'):
+                indents.append(indent)
+        
+    if debug:
+        pysrc_lines.append('    except Exception,e:')
+        pysrc_lines.append('        pysrc, func_name = __debug ')
+        pysrc_lines.append('        lineno = sys.exc_info()[2].tb_lineno')
+        pysrc_lines.append('        print ("Exception in template %s() on "')
+        pysrc_lines.append('               "line %d:" % (func_name, lineno))')
+        pysrc_lines.append('        print pysrc[lineno-1]')
+        pysrc_lines.append('        raise')
+        
+    pysrc = '\n'.join(pysrc_lines)+'\n'
+    #log.debug(pysrc)
+    if debug: localdict = {'__debug': (pysrc_lines, func_name)}
+    else: localdict = {}
+    try: exec pysrc in globals(), localdict
+    except SyntaxError:
+        log.error('Error in script:\n' + pysrc + '\n')
+        raise
+    template_func = localdict[func_name]
+    template_func.__doc__ = docstring
+    return template_func
+    
+def strip_indent(s):
+    """
+    Given a multiline string C{s}, find the minimum indentation for
+    all non-blank lines, and return a new string formed by stripping
+    that amount of indentation from all lines in C{s}.
+    """
+    # Strip indentation from the template.
+    minindent = sys.maxint
+    lines = s.split('\n')
+    for line in lines:
+        stripline = line.lstrip()
+        if stripline:
+            minindent = min(minindent, len(line)-len(stripline))
+    return '\n'.join([l[minindent:] for l in lines])
+
+######################################################################
+## HTML Writer
+######################################################################
+
+class HTMLWriter:
+    #////////////////////////////////////////////////////////////
+    # Table of Contents
+    #////////////////////////////////////////////////////////////
+    #
+    # 1. Interface Methods
+    #
+    # 2. Page Generation -- write complete web page files
+    #   2.1. Module Pages
+    #   2.2. Class Pages
+    #   2.3. Trees Page
+    #   2.4. Indices Page
+    #   2.5. Help Page
+    #   2.6. Frames-based table of contents pages
+    #   2.7. Homepage (index.html)
+    #   2.8. CSS Stylesheet
+    #   2.9. Javascript file
+    #   2.10. Graphs
+    #   2.11. Images
+    #
+    # 3. Page Element Generation -- write pieces of a web page file
+    #   3.1. Page Header
+    #   3.2. Page Footer
+    #   3.3. Navigation Bar
+    #   3.4. Breadcrumbs
+    #   3.5. Summary Tables
+    #
+    # 4. Helper functions
+
+    def __init__(self, docindex, **kwargs):
+        """
+        Construct a new HTML writer, using the given documentation
+        index.
+        
+        @param docindex: The documentation index.
+        
+        @type prj_name: C{string}
+        @keyword prj_name: The name of the project.  Defaults to
+              none.
+        @type prj_url: C{string}
+        @keyword prj_url: The target for the project hopeage link on
+              the navigation bar.  If C{prj_url} is not specified,
+              then no hyperlink is created.
+        @type prj_link: C{string}
+        @keyword prj_link: The label for the project link on the
+              navigation bar.  This link can contain arbitrary HTML
+              code (e.g. images).  By default, a label is constructed
+              from C{prj_name}.
+        @type top_page: C{string}
+        @keyword top_page: The top page for the documentation.  This
+              is the default page shown main frame, when frames are
+              enabled.  C{top} can be a URL, the name of a
+              module, the name of a class, or one of the special
+              strings C{"trees.html"}, C{"indices.html"}, or
+              C{"help.html"}.  By default, the top-level package or
+              module is used, if there is one; otherwise, C{"trees"}
+              is used.
+        @type css: C{string}
+        @keyword css: The CSS stylesheet file.  If C{css} is a file
+              name, then the specified file's conents will be used.
+              Otherwise, if C{css} is the name of a CSS stylesheet in
+              L{epydoc.docwriter.html_css}, then that stylesheet will
+              be used.  Otherwise, an error is reported.  If no stylesheet 
+              is specified, then the default stylesheet is used.
+        @type help_file: C{string}
+        @keyword help_file: The name of the help file.  If no help file is
+              specified, then the default help file will be used.
+        @type show_private: C{boolean}
+        @keyword show_private: Whether to create documentation for
+            private objects.  By default, private objects are documented.
+        @type show_frames: C{boolean})
+        @keyword show_frames: Whether to create a frames-based table of
+              contents.  By default, it is produced.
+        @type show_imports: C{boolean}
+        @keyword show_imports: Whether or not to display lists of
+              imported functions and classes.  By default, they are
+              not shown.
+        @type variable_maxlines: C{int}
+        @keyword variable_maxlines: The maximum number of lines that
+              should be displayed for the value of a variable in the
+              variable details section.  By default, 8 lines are
+              displayed.
+        @type variable_linelength: C{int}
+        @keyword variable_linelength: The maximum line length used for
+              displaying the values of variables in the variable
+              details sections.  If a line is longer than this length,
+              then it will be wrapped to the next line.  The default
+              line length is 70 characters.
+        @type variable_summary_linelength: C{int}
+        @keyword variable_summary_linelength: The maximum line length
+              used for displaying the values of variables in the summary
+              section.  If a line is longer than this length, then it
+              will be truncated.  The default is 40 characters.
+        @type variable_tooltip_linelength: C{int}
+        @keyword variable_tooltip_linelength: The maximum line length
+              used for tooltips for the values of variables.  If a
+              line is longer than this length, then it will be
+              truncated.  The default is 600 characters.
+        @type property_function_linelength: C{int}
+        @keyword property_function_linelength: The maximum line length
+              used to dispaly property functions (C{fget}, C{fset}, and
+              C{fdel}) that contain something other than a function
+              object.  The default length is 40 characters.
+        @type inheritance: C{string}
+        @keyword inheritance: How inherited objects should be displayed.
+              If C{inheritance='grouped'}, then inherited objects are
+              gathered into groups; if C{inheritance='listed'}, then
+              inherited objects are listed in a short list at the
+              end of their group; if C{inheritance='included'}, then
+              inherited objects are mixed in with non-inherited
+              objects.  The default is 'grouped'.
+        @type include_source_code: C{boolean}
+        @keyword include_source_code: If true, then generate colorized
+              source code files for each python module.
+        @type include_log: C{boolean}
+        @keyword include_log: If true, the the footer will include an
+              href to the page 'epydoc-log.html'.
+        @type src_code_tab_width: C{int}
+        @keyword src_code_tab_width: Number of spaces to replace each tab
+            with in source code listings.
+        """
+        self.docindex = docindex
+
+        # Process keyword arguments.
+        self._show_private = kwargs.get('show_private', 1)
+        """Should private docs be included?"""
+        
+        self._prj_name = kwargs.get('prj_name', None)
+        """The project's name (for the project link in the navbar)"""
+        
+        self._prj_url = kwargs.get('prj_url', None)
+        """URL for the project link in the navbar"""
+        
+        self._prj_link = kwargs.get('prj_link', None)
+        """HTML code for the project link in the navbar"""
+        
+        self._top_page = kwargs.get('top_page', None)
+        """The 'main' page"""
+
+        self._css = kwargs.get('css')
+        """CSS stylesheet to use"""
+        
+        self._helpfile = kwargs.get('help_file', None)
+        """Filename of file to extract help contents from"""
+        
+        self._frames_index = kwargs.get('show_frames', 1)
+        """Should a frames index be created?"""
+        
+        self._show_imports = kwargs.get('show_imports', False)
+        """Should imports be listed?"""
+        
+        self._propfunc_linelen = kwargs.get('property_function_linelength', 40)
+        """[XXX] Not used!"""
+        
+        self._variable_maxlines = kwargs.get('variable_maxlines', 8)
+        """Max lines for variable values"""
+        
+        self._variable_linelen = kwargs.get('variable_linelength', 70)
+        """Max line length for variable values"""
+        
+        self._variable_summary_linelen = \
+                         kwargs.get('variable_summary_linelength', 65)
+        """Max length for variable value summaries"""
+        
+        self._variable_tooltip_linelen = \
+                         kwargs.get('variable_tooltip_linelength', 600)
+        """Max length for variable tooltips"""
+        
+        self._inheritance = kwargs.get('inheritance', 'listed')
+        """How should inheritance be displayed?  'listed', 'included',
+        or 'grouped'"""
+
+        self._incl_sourcecode = kwargs.get('include_source_code', True)
+        """Should pages be generated for source code of modules?"""
+
+        self._mark_docstrings = kwargs.get('mark_docstrings', False)
+        """Wrap <span class='docstring'>...</span> around docstrings?"""
+
+        self._graph_types = kwargs.get('graphs', ()) or ()
+        """Graphs that we should include in our output."""
+
+        self._include_log = kwargs.get('include_log', False)
+        """Are we generating an HTML log page?"""
+
+        self._src_code_tab_width = kwargs.get('src_code_tab_width', 8)
+        """Number of spaces to replace each tab with in source code
+        listings."""
+        
+        self._callgraph_cache = {}
+        """Map the callgraph L{uid<DotGraph.uid>} to their HTML
+        representation."""
+
+        self._redundant_details = kwargs.get('redundant_details', False)
+        """If true, then include objects in the details list even if all
+        info about them is already provided by the summary table."""
+
+        # For use with select_variables():
+        if self._show_private:
+            self._public_filter = None
+        else:
+            self._public_filter = True
+        
+        # Make sure inheritance has a sane value.
+        if self._inheritance not in ('listed', 'included', 'grouped'):
+            raise ValueError, 'Bad value for inheritance'
+
+        # Create the project homepage link, if it was not specified.
+        if (self._prj_name or self._prj_url) and not self._prj_link:
+            self._prj_link = plaintext_to_html(self._prj_name or
+                                               'Project Homepage')
+
+        # Add a hyperlink to _prj_url, if _prj_link doesn't already
+        # contain any hyperlinks.
+        if (self._prj_link and self._prj_url and
+            not re.search(r'<a[^>]*\shref', self._prj_link)):
+            self._prj_link = ('<a class="navbar" target="_top" href="'+
+                              self._prj_url+'">'+self._prj_link+'</a>')
+
+        # Precompute lists & sets of APIDoc objects that we're
+        # interested in.
+        self.valdocs = valdocs = sorted(docindex.reachable_valdocs(
+            imports=False, packages=False, bases=False, submodules=False, 
+            subclasses=False, private=self._show_private))
+        self.module_list = [d for d in valdocs if isinstance(d, ModuleDoc)]
+        """The list of L{ModuleDoc}s for the documented modules."""
+        self.module_set = set(self.module_list)
+        """The set of L{ModuleDoc}s for the documented modules."""
+        self.class_list = [d for d in valdocs if isinstance(d, ClassDoc)]
+        """The list of L{ClassDoc}s for the documented classes."""
+        self.class_set = set(self.class_list)
+        """The set of L{ClassDoc}s for the documented classes."""
+        self.routine_list = [d for d in valdocs if isinstance(d, RoutineDoc)]
+        """The list of L{RoutineDoc}s for the documented routines."""
+        self.indexed_docs = []
+        """The list of L{APIDoc}s for variables and values that should
+        be included in the index."""
+
+        # URL for 'trees' page
+        if self.module_list: self._trees_url = 'module-tree.html'
+        else: self._trees_url = 'class-tree.html'
+
+        # Construct the value for self.indexed_docs.
+        self.indexed_docs += [d for d in valdocs
+                              if not isinstance(d, GenericValueDoc)]
+        for doc in valdocs:
+            if isinstance(doc, NamespaceDoc):
+                # add any vars with generic values; but don't include
+                # inherited vars.
+                self.indexed_docs += [d for d in doc.variables.values() if
+                                      isinstance(d.value, GenericValueDoc)
+                                      and d.container == doc]
+        self.indexed_docs.sort()
+
+        # Figure out the url for the top page.
+        self._top_page_url = self._find_top_page(self._top_page)
+
+        # Decide whether or not to split the identifier index.
+        self._split_ident_index = (len(self.indexed_docs) >=
+                                   self.SPLIT_IDENT_INDEX_SIZE)
+        
+        # Figure out how many output files there will be (for progress
+        # reporting).
+        self.modules_with_sourcecode = set()
+        for doc in self.module_list:
+            if isinstance(doc, ModuleDoc) and is_src_filename(doc.filename):
+                self.modules_with_sourcecode.add(doc)
+        self._num_files = (len(self.class_list) + len(self.module_list) +
+                           10 + len(self.METADATA_INDICES))
+        if self._frames_index:
+            self._num_files += len(self.module_list) + 3
+
+        if self._incl_sourcecode:
+            self._num_files += len(self.modules_with_sourcecode)
+        if self._split_ident_index:
+            self._num_files += len(self.LETTERS)
+            
+    def _find_top_page(self, pagename):
+        """
+        Find the top page for the API documentation.  This page is
+        used as the default page shown in the main frame, when frames
+        are used.  When frames are not used, this page is copied to 
+        C{index.html}.
+
+        @param pagename: The name of the page, as specified by the
+            keyword argument C{top} to the constructor.
+        @type pagename: C{string}
+        @return: The URL of the top page.
+        @rtype: C{string}
+        """
+        # If a page name was specified, then we need to figure out
+        # what it points to.
+        if pagename:
+            # If it's a URL, then use it directly.
+            if pagename.lower().startswith('http:'):
+                return pagename
+
+            # If it's an object, then use that object's page.
+            try:
+                doc = self.docindex.get_valdoc(pagename)
+                return self.url(doc)
+            except:
+                pass
+
+            # Otherwise, give up.
+            log.warning('Could not find top page %r; using %s '
+                        'instead' % (pagename, self._trees_url))
+            return self._trees_url
+
+        # If no page name was specified, then try to choose one
+        # automatically.
+        else:
+            root = [val_doc for val_doc in self.docindex.root
+                    if isinstance(val_doc, (ClassDoc, ModuleDoc))]
+            if len(root) == 0:
+                # No docs??  Try the trees page.
+                return self._trees_url
+            elif len(root) == 1:
+                # One item in the root; use that.
+                return self.url(root[0]) 
+            else:
+                # Multiple root items; if they're all in one package,
+                # then use that.  Otherwise, use self._trees_url
+                root = sorted(root, key=lambda v:len(v.canonical_name))
+                top = root[0]
+                for doc in root[1:]:
+                    if not top.canonical_name.dominates(doc.canonical_name):
+                        return self._trees_url
+                else:
+                    return self.url(top)
+    
+    #////////////////////////////////////////////////////////////
+    #{ 1. Interface Methods
+    #////////////////////////////////////////////////////////////
+
+    def write(self, directory=None):
+        """
+        Write the documentation to the given directory.
+
+        @type directory: C{string}
+        @param directory: The directory to which output should be
+            written.  If no directory is specified, output will be
+            written to the current directory.  If the directory does
+            not exist, it will be created.
+        @rtype: C{None}
+        @raise OSError: If C{directory} cannot be created.
+        @raise OSError: If any file cannot be created or written to.
+        """
+        # For progress reporting:
+        self._files_written = 0.
+        
+        # Set the default values for ValueDoc formatted representations.
+        orig_valdoc_defaults = (ValueDoc.SUMMARY_REPR_LINELEN,
+                                ValueDoc.REPR_LINELEN,
+                                ValueDoc.REPR_MAXLINES)
+        ValueDoc.SUMMARY_REPR_LINELEN = self._variable_summary_linelen
+        ValueDoc.REPR_LINELEN = self._variable_linelen
+        ValueDoc.REPR_MAXLINES = self._variable_maxlines
+
+        # Use an image for the crarr symbol.
+        from epydoc.markup.epytext import ParsedEpytextDocstring
+        orig_crarr_html = ParsedEpytextDocstring.SYMBOL_TO_HTML['crarr']
+        ParsedEpytextDocstring.SYMBOL_TO_HTML['crarr'] = (
+            r'<span class="variable-linewrap">'
+            r'<img src="crarr.png" alt="\" /></span>')
+
+        # Keep track of failed xrefs, and report them at the end.
+        self._failed_xrefs = {}
+
+        # Create destination directories, if necessary
+        if not directory: directory = os.curdir
+        self._mkdir(directory)
+        self._directory = directory
+
+        # Write the CSS file.
+        self._files_written += 1
+        log.progress(self._files_written/self._num_files, 'epydoc.css')
+        self.write_css(directory, self._css)
+
+        # Write the Javascript file.
+        self._files_written += 1
+        log.progress(self._files_written/self._num_files, 'epydoc.js')
+        self.write_javascript(directory)
+
+        # Write images
+        self.write_images(directory)
+
+        # Build the indices.
+        indices = {'ident': self.build_identifier_index(),
+                   'term': self.build_term_index()}
+        for (name, label, label2) in self.METADATA_INDICES:
+            indices[name] = self.build_metadata_index(name)
+
+        # Write the identifier index.  If requested, split it into
+        # separate pages for each letter.
+        ident_by_letter = self._group_by_letter(indices['ident'])
+        if not self._split_ident_index:
+            self._write(self.write_link_index, directory,
+                        'identifier-index.html', indices,
+                        'Identifier Index', 'identifier-index.html',
+                        ident_by_letter)
+        else:
+            # Write a page for each section.
+            for letter in self.LETTERS:
+                filename = 'identifier-index-%s.html' % letter
+                self._write(self.write_link_index, directory, filename,
+                            indices, 'Identifier Index', filename,
+                            ident_by_letter, [letter],
+                            'identifier-index-%s.html')
+            # Use the first non-empty section as the main index page.
+            for letter in self.LETTERS:
+                if letter in ident_by_letter:
+                    filename = 'identifier-index.html'
+                    self._write(self.write_link_index, directory, filename,
+                                indices, 'Identifier Index', filename,
+                                ident_by_letter, [letter], 
+                                'identifier-index-%s.html')
+                    break
+
+        # Write the term index.
+        if indices['term']:
+            term_by_letter = self._group_by_letter(indices['term'])
+            self._write(self.write_link_index, directory, 'term-index.html',
+                        indices, 'Term Definition Index',
+                        'term-index.html', term_by_letter)
+        else:
+            self._files_written += 1 # (skipped)
+
+        # Write the metadata indices.
+        for (name, label, label2) in self.METADATA_INDICES:
+            if indices[name]:
+                self._write(self.write_metadata_index, directory,
+                            '%s-index.html' % name, indices, name,
+                            label, label2)
+            else:
+                self._files_written += 1 # (skipped)
+
+        # Write the trees file (package & class hierarchies)
+        if self.module_list:
+            self._write(self.write_module_tree, directory, 'module-tree.html')
+        else:
+            self._files_written += 1 # (skipped)
+        if self.class_list:
+            self._write(self.write_class_tree, directory, 'class-tree.html')
+        else:
+            self._files_written += 1 # (skipped)
+        
+        # Write the help file.
+        self._write(self.write_help, directory,'help.html')
+        
+        # Write the frames-based table of contents.
+        if self._frames_index:
+            self._write(self.write_frames_index, directory, 'frames.html')
+            self._write(self.write_toc, directory, 'toc.html')
+            self._write(self.write_project_toc, directory, 'toc-everything.html')
+            for doc in self.module_list:
+                filename = 'toc-%s' % urllib.unquote(self.url(doc))
+                self._write(self.write_module_toc, directory, filename, doc)
+
+        # Write the object documentation.
+        for doc in self.module_list:
+            filename = urllib.unquote(self.url(doc))
+            self._write(self.write_module, directory, filename, doc)
+        for doc in self.class_list:
+            filename = urllib.unquote(self.url(doc))
+            self._write(self.write_class, directory, filename, doc)
+
+        # Write source code files.
+        if self._incl_sourcecode:
+            # Build a map from short names to APIDocs, used when
+            # linking names in the source code.
+            name_to_docs = {}
+            for api_doc in self.indexed_docs:
+                if (api_doc.canonical_name is not None and
+                    self.url(api_doc) is not None):
+                    name = api_doc.canonical_name[-1]
+                    name_to_docs.setdefault(name, []).append(api_doc)
+            # Sort each entry of the name_to_docs list.
+            for doc_list in name_to_docs.values():
+                doc_list.sort()
+            # Write the source code for each module.
+            for doc in self.modules_with_sourcecode:
+                filename = urllib.unquote(self.pysrc_url(doc))
+                self._write(self.write_sourcecode, directory, filename, doc,
+                            name_to_docs)
+
+        # Write the auto-redirect page.
+        self._write(self.write_redirect_page, directory, 'redirect.html')
+
+        # Write the mapping object name -> URL
+        self._write(self.write_api_list, directory, 'api-objects.txt')
+        
+        # Write the index.html files.
+        # (this must be done last, since it might copy another file)
+        self._files_written += 1
+        log.progress(self._files_written/self._num_files, 'index.html')
+        self.write_homepage(directory)
+
+        # Don't report references to builtins as missing
+        for k in self._failed_xrefs.keys(): # have a copy of keys
+            if hasattr(__builtin__, k):
+                del self._failed_xrefs[k]
+
+        # Report any failed crossreferences
+        if self._failed_xrefs:
+            estr = 'Failed identifier crossreference targets:\n'
+            failed_identifiers = self._failed_xrefs.keys()
+            failed_identifiers.sort()
+            for identifier in failed_identifiers:
+                names = self._failed_xrefs[identifier].keys()
+                names.sort()
+                estr += '- %s' % identifier
+                estr += '\n'
+                for name in names:
+                    estr += '      (from %s)\n' % name
+            log.docstring_warning(estr)
+
+        # [xx] testing:
+        if self._num_files != int(self._files_written):
+            log.debug("Expected to write %d files, but actually "
+                      "wrote %d files" %
+                      (self._num_files, int(self._files_written)))
+
+        # Restore defaults that we changed.
+        (ValueDoc.SUMMARY_REPR_LINELEN, ValueDoc.REPR_LINELEN,
+         ValueDoc.REPR_MAXLINES) = orig_valdoc_defaults
+        ParsedEpytextDocstring.SYMBOL_TO_HTML['crarr'] = orig_crarr_html
+
+    def _write(self, write_func, directory, filename, *args):
+        # Display our progress.
+        self._files_written += 1
+        log.progress(self._files_written/self._num_files, filename)
+        
+        path = os.path.join(directory, filename)
+        f = codecs.open(path, 'w', 'ascii', errors='xmlcharrefreplace')
+        write_func(f.write, *args)
+        f.close()
+
+    def _mkdir(self, directory):
+        """
+        If the given directory does not exist, then attempt to create it.
+        @rtype: C{None}
+        """
+        if not os.path.isdir(directory):
+            if os.path.exists(directory):
+                raise OSError('%r is not a directory' % directory)
+            os.mkdir(directory)
+        
+    #////////////////////////////////////////////////////////////
+    #{ 2.1. Module Pages
+    #////////////////////////////////////////////////////////////
+
+    def write_module(self, out, doc):
+        """
+        Write an HTML page containing the API documentation for the
+        given module to C{out}.
+        
+        @param doc: A L{ModuleDoc} containing the API documentation
+        for the module that should be described.
+        """
+        longname = doc.canonical_name
+        shortname = doc.canonical_name[-1]
+
+        # Write the page header (incl. navigation bar & breadcrumbs)
+        self.write_header(out, str(longname))
+        self.write_navbar(out, doc)
+        self.write_breadcrumbs(out, doc, self.url(doc))
+
+        # Write the name of the module we're describing.
+        if doc.is_package is True: typ = 'Package'
+        else: typ = 'Module'
+        if longname[0].startswith('script-'):
+            shortname = str(longname)[7:]
+            typ = 'Script'
+        out('<!-- ==================== %s ' % typ.upper() +
+            'DESCRIPTION ==================== -->\n')
+        out('<h1 class="epydoc">%s %s</h1>' % (typ, shortname))
+        out('<p class="nomargin-top">%s</p>\n' % self.pysrc_link(doc))
+        
+        # If the module has a description, then list it.
+        if doc.descr not in (None, UNKNOWN):
+            out(self.descr(doc, 2)+'\n\n')
+
+        # Write any standarad metadata (todo, author, etc.)
+        if doc.metadata is not UNKNOWN and doc.metadata:
+            out('<hr />\n')
+        self.write_standard_fields(out, doc)
+
+        # If it's a package, then list the modules it contains.
+        if doc.is_package is True:
+            self.write_module_list(out, doc)
+
+        # Write summary tables describing the variables that the
+        # module defines.
+        self.write_summary_table(out, "Classes", doc, "class")
+        self.write_summary_table(out, "Functions", doc, "function")
+        self.write_summary_table(out, "Variables", doc, "other")
+
+        # Write a list of all imported objects.
+        if self._show_imports:
+            self.write_imports(out, doc)
+
+        # Write detailed descriptions of functions & variables defined
+        # in this module.
+        self.write_details_list(out, "Function Details", doc, "function")
+        self.write_details_list(out, "Variables Details", doc, "other")
+
+        # Write the page footer (including navigation bar)
+        self.write_navbar(out, doc)
+        self.write_footer(out)
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.??. Source Code Pages
+    #////////////////////////////////////////////////////////////
+
+    def write_sourcecode(self, out, doc, name_to_docs):
+        #t0 = time.time()
+        
+        filename = doc.filename
+        name = str(doc.canonical_name)
+        
+        # Header
+        self.write_header(out, name)
+        self.write_navbar(out, doc)
+        self.write_breadcrumbs(out, doc, self.pysrc_url(doc))
+
+        # Source code listing
+        out('<h1 class="epydoc">Source Code for %s</h1>\n' %
+            self.href(doc, label='%s %s' % (self.doc_kind(doc), name)))
+        out('<pre class="py-src">\n')
+        out(PythonSourceColorizer(filename, name, self.docindex,
+                                  self.url, name_to_docs,
+                                  self._src_code_tab_width).colorize())
+        out('</pre>\n<br />\n')
+
+        # Footer
+        self.write_navbar(out, doc)
+        self.write_footer(out)
+        
+        #log.debug('[%6.2f sec] Wrote pysrc for %s' %
+        #          (time.time()-t0, name))
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.2. Class Pages
+    #////////////////////////////////////////////////////////////
+
+    def write_class(self, out, doc):
+        """
+        Write an HTML page containing the API documentation for the
+        given class to C{out}.
+        
+        @param doc: A L{ClassDoc} containing the API documentation
+        for the class that should be described.
+        """
+        longname = doc.canonical_name
+        shortname = doc.canonical_name[-1]
+
+        # Write the page header (incl. navigation bar & breadcrumbs)
+        self.write_header(out, str(longname))
+        self.write_navbar(out, doc)
+        self.write_breadcrumbs(out, doc, self.url(doc))
+
+        # Write the name of the class we're describing.
+        if doc.is_type(): typ = 'Type'
+        elif doc.is_exception(): typ = 'Exception'
+        else: typ = 'Class'
+        out('<!-- ==================== %s ' % typ.upper() +
+            'DESCRIPTION ==================== -->\n')
+        out('<h1 class="epydoc">%s %s</h1>' % (typ, shortname))
+        out('<p class="nomargin-top">%s</p>\n' % self.pysrc_link(doc))
+
+        if ((doc.bases not in (UNKNOWN, None) and len(doc.bases) > 0) or
+            (doc.subclasses not in (UNKNOWN,None) and len(doc.subclasses)>0)):
+            # Display bases graphically, if requested.
+            if 'umlclasstree' in self._graph_types:
+                self.write_class_tree_graph(out, doc, uml_class_tree_graph)
+            elif 'classtree' in self._graph_types:
+                self.write_class_tree_graph(out, doc, class_tree_graph)
+                
+            # Otherwise, use ascii-art.
+            else:
+                # Write the base class tree.
+                if doc.bases not in (UNKNOWN, None) and len(doc.bases) > 0:
+                    out('<pre class="base-tree">\n%s</pre>\n\n' %
+                        self.base_tree(doc))
+
+                # Write the known subclasses
+                if (doc.subclasses not in (UNKNOWN, None) and
+                    len(doc.subclasses) > 0):
+                    out('<dl><dt>Known Subclasses:</dt>\n<dd>\n    ')
+                    out('  <ul class="subclass-list">\n')
+                    for i, subclass in enumerate(doc.subclasses):
+                        href = self.href(subclass, context=doc)
+                        if self._val_is_public(subclass): css = ''
+                        else: css = ' class="private"'
+                        if i > 0: href = ', '+href
+                        out('<li%s>%s</li>' % (css, href))
+                    out('  </ul>\n')
+                    out('</dd></dl>\n\n')
+
+            out('<hr />\n')
+        
+        # If the class has a description, then list it.
+        if doc.descr not in (None, UNKNOWN):
+            out(self.descr(doc, 2)+'\n\n')
+
+        # Write any standarad metadata (todo, author, etc.)
+        if doc.metadata is not UNKNOWN and doc.metadata:
+            out('<hr />\n')
+        self.write_standard_fields(out, doc)
+
+        # Write summary tables describing the variables that the
+        # class defines.
+        self.write_summary_table(out, "Nested Classes", doc, "class")
+        self.write_summary_table(out, "Instance Methods", doc,
+                                 "instancemethod")
+        self.write_summary_table(out, "Class Methods", doc, "classmethod")
+        self.write_summary_table(out, "Static Methods", doc, "staticmethod")
+        self.write_summary_table(out, "Class Variables", doc,
+                                 "classvariable")
+        self.write_summary_table(out, "Instance Variables", doc,
+                                 "instancevariable")
+        self.write_summary_table(out, "Properties", doc, "property")
+
+        # Write a list of all imported objects.
+        if self._show_imports:
+            self.write_imports(out, doc)
+
+        # Write detailed descriptions of functions & variables defined
+        # in this class.
+        # [xx] why group methods into one section but split vars into two?
+        # seems like we should either group in both cases or split in both
+        # cases.
+        self.write_details_list(out, "Method Details", doc, "method")
+        self.write_details_list(out, "Class Variable Details", doc,
+                                "classvariable")
+        self.write_details_list(out, "Instance Variable Details", doc,
+                                "instancevariable")
+        self.write_details_list(out, "Property Details", doc, "property")
+
+        # Write the page footer (including navigation bar)
+        self.write_navbar(out, doc)
+        self.write_footer(out)
+
+    def write_class_tree_graph(self, out, doc, graphmaker):
+        """
+        Write HTML code for a class tree graph of C{doc} (a classdoc),
+        using C{graphmaker} to draw the actual graph.  C{graphmaker}
+        should be L{class_tree_graph()}, or L{uml_class_tree_graph()},
+        or any other function with a compatible signature.
+
+        If the given class has any private sublcasses (including
+        recursive subclasses), then two graph images will be generated
+        -- one to display when private values are shown, and the other
+        to display when private values are hidden.
+        """
+        linker = _HTMLDocstringLinker(self, doc)
+        private_subcls = self._private_subclasses(doc)
+        if private_subcls:
+            out('<center>\n'
+                '  <div class="private">%s</div>\n'
+                '  <div class="public" style="display:none">%s</div>\n'
+                '</center>\n' %
+                (self.render_graph(graphmaker(doc, linker, doc)),
+                 self.render_graph(graphmaker(doc, linker, doc,
+                                              exclude=private_subcls))))
+        else:
+            out('<center>\n%s\n</center>\n' %
+                self.render_graph(graphmaker(doc, linker, doc)))
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.3. Trees pages
+    #////////////////////////////////////////////////////////////
+
+    def write_module_tree(self, out):
+        # Header material
+        self.write_treepage_header(out, 'Module Hierarchy', 'module-tree.html')
+        out('<h1 class="epydoc">Module Hierarchy</h1>\n')
+
+        # Write entries for all top-level modules/packages.
+        out('<ul class="nomargin-top">\n')
+        for doc in self.module_list:
+            if (doc.package in (None, UNKNOWN) or
+                doc.package not in self.module_set):
+                self.write_module_tree_item(out, doc)
+        out('</ul>\n')
+
+        # Footer material
+        self.write_navbar(out, 'trees')
+        self.write_footer(out)
+
+    def write_class_tree(self, out):
+        """
+        Write HTML code for a nested list showing the base/subclass
+        relationships between all documented classes.  Each element of
+        the top-level list is a class with no (documented) bases; and
+        under each class is listed all of its subclasses.  Note that
+        in the case of multiple inheritance, a class may appear
+        multiple times.  
+        
+        @todo: For multiple inheritance, don't repeat subclasses the
+            second time a class is mentioned; instead, link to the
+            first mention.
+        """
+        # [XX] backref for multiple inheritance?
+        # Header material
+        self.write_treepage_header(out, 'Class Hierarchy', 'class-tree.html')
+        out('<h1 class="epydoc">Class Hierarchy</h1>\n')
+
+        # Build a set containing all classes that we should list.
+        # This includes everything in class_list, plus any of those
+        # class' bases, but not undocumented subclasses.
+        class_set = self.class_set.copy()
+        for doc in self.class_list:
+            if doc.bases != UNKNOWN:
+                for base in doc.bases:
+                    if base not in class_set:
+                        if isinstance(base, ClassDoc):
+                            class_set.update(base.mro())
+                        else:
+                            # [XX] need to deal with this -- how?
+                            pass
+                            #class_set.add(base)
+ 
+        out('<ul class="nomargin-top">\n')
+        for doc in sorted(class_set, key=lambda c:c.canonical_name[-1]):
+            if doc.bases != UNKNOWN and len(doc.bases)==0:
+                self.write_class_tree_item(out, doc, class_set)
+        out('</ul>\n')
+        
+        # Footer material
+        self.write_navbar(out, 'trees')
+        self.write_footer(out)
+
+    def write_treepage_header(self, out, title, url):
+        # Header material.
+        self.write_header(out, title)
+        self.write_navbar(out, 'trees')
+        self.write_breadcrumbs(out, 'trees', url)
+        if self.class_list and self.module_list:
+            out('<center><b>\n')
+            out(' [ <a href="module-tree.html">Module Hierarchy</a>\n')
+            out(' | <a href="class-tree.html">Class Hierarchy</a> ]\n')
+            out('</b></center><br />\n')
+
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.4. Index pages
+    #////////////////////////////////////////////////////////////
+
+    SPLIT_IDENT_INDEX_SIZE = 3000
+    """If the identifier index has more than this number of entries,
+    then it will be split into separate pages, one for each
+    alphabetical section."""
+
+    LETTERS = 'ABCDEFGHIJKLMNOPQRSTUVWXYZ_'
+    """The alphabetical sections that are used for link index pages."""
+    
+    def write_link_index(self, out, indices, title, url, index_by_section,
+                         sections=LETTERS, section_url='#%s'):
+        
+        # Header
+        self.write_indexpage_header(out, indices, title, url)
+
+        # Index title & links to alphabetical sections.
+        out('<table border="0" width="100%">\n'
+            '<tr valign="bottom"><td>\n')
+        out('<h1 class="epydoc">%s</h1>\n</td><td>\n[\n' % title)
+        for sec in self.LETTERS:
+            if sec in index_by_section:
+                out(' <a href="%s">%s</a>\n' % (section_url % sec, sec))
+            else:
+                out('  %s\n' % sec)
+        out(']\n')
+        out('</td></table>\n')
+
+        # Alphabetical sections.
+        sections = [s for s in sections if s in index_by_section]
+        if sections:
+            out('<table border="0" width="100%">\n')
+            for section in sorted(sections):
+                out('<tr valign="top"><td valign="top" width="1%">')
+                out('<h2 class="epydoc"><a name="%s">%s</a></h2></td>\n' %
+                    (section, section))
+                out('<td valign="top">\n')
+                self.write_index_section(out, index_by_section[section], True)
+                out('</td></tr>\n')
+            out('</table>\n<br />')
+
+        # Footer material.
+        out('<br />')
+        self.write_navbar(out, 'indices')
+        self.write_footer(out)
+                
+        
+    def write_metadata_index(self, out, indices, field, title, typ):
+        """
+        Write an HTML page containing a metadata index.
+        """
+        index = indices[field]
+        
+        # Header material.
+        self.write_indexpage_header(out, indices, title,
+                                    '%s-index.html' % field)
+
+        # Page title.
+        out('<h1 class="epydoc"><a name="%s">%s</a></h1>\n<br />\n' %
+            (field, title))
+
+        # Index (one section per arg)
+        for arg in sorted(index):
+            # Write a section title.
+            if arg is not None:
+                if len([1 for (doc, descrs) in index[arg] if
+                        not self._doc_or_ancestor_is_private(doc)]) == 0:
+                    out('<div class="private">')
+                else:
+                    out('<div>')
+                self.write_table_header(out, 'metadata-index', arg)
+                out('</table>')
+            # List every descr for this arg.
+            for (doc, descrs) in index[arg]:
+                if self._doc_or_ancestor_is_private(doc):
+                    out('<div class="private">\n')
+                else:
+                    out('<div>\n')
+                out('<table width="100%" class="metadata-index" '
+                    'bgcolor="#e0e0e0"><tr><td class="metadata-index">')
+                out('<b>%s in %s</b>' %
+                    (typ, self.href(doc, label=doc.canonical_name)))
+                out('    <ul class="nomargin">\n')
+                for descr in descrs:
+                    out('      <li>%s</li>\n' %
+                        self.docstring_to_html(descr,doc,4))
+                out('    </ul>\n')
+                out('</table></div>\n')
+
+        # Footer material.
+        out('<br />')
+        self.write_navbar(out, 'indices')
+        self.write_footer(out)
+
+    def write_indexpage_header(self, out, indices, title, url):
+        """
+        A helper for the index page generation functions, which
+        generates a header that can be used to navigate between the
+        different indices.
+        """
+        self.write_header(out, title)
+        self.write_navbar(out, 'indices')
+        self.write_breadcrumbs(out, 'indices', url)
+
+        if (indices['term'] or
+            [1 for (name,l,l2) in self.METADATA_INDICES if indices[name]]):
+            out('<center><b>[\n')
+            out(' <a href="identifier-index.html">Identifiers</a>\n')
+            if indices['term']:
+                out('| <a href="term-index.html">Term Definitions</a>\n')
+            for (name, label, label2) in self.METADATA_INDICES:
+                if indices[name]:
+                    out('| <a href="%s-index.html">%s</a>\n' %
+                        (name, label2))
+            out(']</b></center><br />\n')
+
+    def write_index_section(self, out, items, add_blankline=False):
+        out('<table class="link-index" width="100%" border="1">\n')
+        num_rows = (len(items)+2)/3
+        for row in range(num_rows):
+            out('<tr>\n')
+            for col in range(3):
+                out('<td width="33%" class="link-index">')
+                i = col*num_rows+row
+                if i < len(items):
+                    name, url, container = items[col*num_rows+row]
+                    out('<a href="%s">%s</a>' % (url, name))
+                    if container is not None:
+                        out('<br />\n')
+                        if isinstance(container, ModuleDoc):
+                            label = container.canonical_name
+                        else:
+                            label = container.canonical_name[-1]
+                        out('<span class="index-where">(in&nbsp;%s)'
+                            '</span>' % self.href(container, label))
+                else:
+                    out('&nbsp;')
+                out('</td>\n')
+            out('</tr>\n')
+            if add_blankline and num_rows == 1:
+                blank_cell = '<td class="link-index">&nbsp;</td>'
+                out('<tr>'+3*blank_cell+'</tr>\n')
+        out('</table>\n')
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.5. Help Page
+    #////////////////////////////////////////////////////////////
+
+    def write_help(self, out):
+        """
+        Write an HTML help file to the given stream.  If
+        C{self._helpfile} contains a help file, then use it;
+        otherwise, use the default helpfile from
+        L{epydoc.docwriter.html_help}.
+        """
+        # todo: optionally parse .rst etc help files?
+        
+        # Get the contents of the help file.
+        if self._helpfile:
+            if os.path.exists(self._helpfile):
+                try: help = open(self._helpfile).read()
+                except: raise IOError("Can't open help file: %r" %
+                                      self._helpfile)
+            else:
+                raise IOError("Can't find help file: %r" % self._helpfile)
+        else:
+            if self._prj_name: thisprj = self._prj_name
+            else: thisprj = 'this project'
+            help = HTML_HELP % {'this_project':thisprj}
+
+        # Insert the help contents into a webpage.
+        self.write_header(out, 'Help')
+        self.write_navbar(out, 'help')
+        self.write_breadcrumbs(out, 'help', 'help.html')
+        out(help)
+        self.write_navbar(out, 'help')
+        self.write_footer(out)
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.6. Frames-based Table of Contents
+    #////////////////////////////////////////////////////////////
+    
+    write_frames_index = compile_template(
+        """
+        write_frames_index(self, out)
+
+        Write the frames index file for the frames-based table of
+        contents to the given streams.
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        <?xml version="1.0" encoding="iso-8859-1"?>
+        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Frameset//EN"
+                  "DTD/xhtml1-frameset.dtd">
+        <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+        <head>
+          <title> $self._prj_name or "API Documentation"$ </title>
+        </head>
+        <frameset cols="20%,80%">
+          <frameset rows="30%,70%">
+            <frame src="toc.html" name="moduleListFrame"
+                   id="moduleListFrame" />
+            <frame src="toc-everything.html" name="moduleFrame"
+                   id="moduleFrame" />
+          </frameset>
+          <frame src="$self._top_page_url$" name="mainFrame" id="mainFrame" />
+        </frameset>
+        </html>
+        ''')
+        # \------------------------------------------------------------/
+    
+    write_toc = compile_template(
+        """
+        write_toc(self, out)
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        >>> self.write_header(out, "Table of Contents")
+        <h1 class="toc">Table&nbsp;of&nbsp;Contents</h1>
+        <hr />
+          <a target="moduleFrame" href="toc-everything.html">Everything</a>
+          <br />
+        >>> self.write_toc_section(out, "Modules", self.module_list)
+        <hr />
+        >>> if self._show_private:
+          $self.PRIVATE_LINK$
+        >>> #endif
+        >>> self.write_footer(out, short=True)
+        ''')
+        # \------------------------------------------------------------/
+
+    def write_toc_section(self, out, name, docs, fullname=True):
+        if not docs: return
+
+        # Assign names to each item, and sort by name.
+        if fullname:
+            docs = [(str(d.canonical_name), d) for d in docs]
+        else:
+            docs = [(str(d.canonical_name[-1]), d) for d in docs]
+        docs.sort()
+
+        out('  <h2 class="toc">%s</h2>\n' % name)
+        for label, doc in docs:
+            doc_url = self.url(doc)
+            toc_url = 'toc-%s' % doc_url
+            is_private = self._doc_or_ancestor_is_private(doc)
+            if is_private:
+                if not self._show_private: continue
+                out('  <div class="private">\n')
+                
+            if isinstance(doc, ModuleDoc):
+                out('    <a target="moduleFrame" href="%s"\n'
+                    '     onclick="setFrame(\'%s\',\'%s\');"'
+                    '     >%s</a><br />' % (toc_url, toc_url, doc_url, label))
+            else:
+                out('    <a target="mainFrame" href="%s"\n'
+                    '     >%s</a><br />' % (doc_url, label))
+            if is_private:
+                out('  </div>\n')
+
+    def write_project_toc(self, out):
+        self.write_header(out, "Everything")
+        out('<h1 class="toc">Everything</h1>\n')
+        out('<hr />\n')
+
+        # List the classes.
+        self.write_toc_section(out, "All Classes", self.class_list)
+
+        # List the functions.
+        funcs = [d for d in self.routine_list 
+                 if not isinstance(self.docindex.container(d), 
+                                   (ClassDoc, types.NoneType))]
+        self.write_toc_section(out, "All Functions", funcs)
+
+        # List the variables.
+        vars = []
+        for doc in self.module_list:
+            vars += doc.select_variables(value_type='other',
+                                         imported=False,
+                                         public=self._public_filter)
+        self.write_toc_section(out, "All Variables", vars)
+
+        # Footer material.
+        out('<hr />\n')
+        if self._show_private:
+            out(self.PRIVATE_LINK+'\n')
+        self.write_footer(out, short=True)
+
+    def write_module_toc(self, out, doc):
+        """
+        Write an HTML page containing the table of contents page for
+        the given module to the given streams.  This page lists the
+        modules, classes, exceptions, functions, and variables defined
+        by the module.
+        """
+        name = doc.canonical_name[-1]
+        self.write_header(out, name)
+        out('<h1 class="toc">Module %s</h1>\n' % name)
+        out('<hr />\n')
+
+
+        # List the classes.
+        classes = doc.select_variables(value_type='class', imported=False,
+                                       public=self._public_filter)
+        self.write_toc_section(out, "Classes", classes, fullname=False)
+
+        # List the functions.
+        funcs = doc.select_variables(value_type='function', imported=False,
+                                     public=self._public_filter)
+        self.write_toc_section(out, "Functions", funcs, fullname=False)
+
+        # List the variables.
+        variables = doc.select_variables(value_type='other', imported=False,
+                                         public=self._public_filter)
+        self.write_toc_section(out, "Variables", variables, fullname=False)
+        
+        # Footer material.
+        out('<hr />\n')
+        if self._show_private:
+            out(self.PRIVATE_LINK+'\n')
+        self.write_footer(out, short=True)
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.7. Project homepage (index.html)
+    #////////////////////////////////////////////////////////////
+
+    def write_homepage(self, directory):
+        """
+        Write an C{index.html} file in the given directory.  The
+        contents of this file are copied or linked from an existing
+        page, so this method must be called after all pages have been
+        written.  The page used is determined by L{_frames_index} and
+        L{_top_page}:
+            - If L{_frames_index} is true, then C{frames.html} is
+              copied.
+            - Otherwise, the page specified by L{_top_page} is
+              copied.
+        """
+        filename = os.path.join(directory, 'index.html')
+        if self._frames_index: top = 'frames.html'
+        else: top = self._top_page_url
+
+        # Copy the non-frames index file from top, if it's internal.
+        if top[:5] != 'http:' and '/' not in top:
+            try:
+                # Read top into `s`.
+                topfile = os.path.join(directory, top)
+                s = open(topfile, 'r').read()
+
+                # Write the output file.
+                open(filename, 'w').write(s)
+                return
+            except:
+                log.error('Warning: error copying index; '
+                          'using a redirect page')
+
+        # Use a redirect if top is external, or if we faild to copy.
+        name = self._prj_name or 'this project'
+        f = open(filename, 'w')
+        self.write_redirect_index(f.write, top, name)
+        f.close()
+
+    write_redirect_index = compile_template(
+        """
+        write_redirect_index(self, out, top, name)
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        <?xml version="1.0" encoding="iso-8859-1"?>
+        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
+                  "DTD/xhtml1-strict.dtd">
+        <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+        <head>
+          <title> Redirect </title>
+          <meta http-equiv="refresh" content="1;url=$top$" />
+          <link rel="stylesheet" href="epydoc.css" type="text/css"></link>
+        </head>
+        <body>
+          <p>Redirecting to the API documentation for
+            <a href="$top$">$self._prj_name or "this project"$</a>...</p>
+        </body>
+        </html>
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.8. Stylesheet (epydoc.css)
+    #////////////////////////////////////////////////////////////
+
+    def write_css(self, directory, cssname):
+        """
+        Write the CSS stylesheet in the given directory.  If
+        C{cssname} contains a stylesheet file or name (from
+        L{epydoc.docwriter.html_css}), then use that stylesheet;
+        otherwise, use the default stylesheet.
+
+        @rtype: C{None}
+        """
+        filename = os.path.join(directory, 'epydoc.css')
+        
+        # Get the contents for the stylesheet file.
+        if cssname is None:
+            css = STYLESHEETS['default'][0]
+        else:
+            if os.path.exists(cssname):
+                try: css = open(cssname).read()
+                except: raise IOError("Can't open CSS file: %r" % cssname)
+            elif cssname in STYLESHEETS:
+                css = STYLESHEETS[cssname][0]
+            else:
+                raise IOError("Can't find CSS file: %r" % cssname)
+
+        # Write the stylesheet.
+        cssfile = open(filename, 'w')
+        cssfile.write(css)
+        cssfile.close()
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.9. Javascript (epydoc.js)
+    #////////////////////////////////////////////////////////////
+
+    def write_javascript(self, directory):
+        jsfile = open(os.path.join(directory, 'epydoc.js'), 'w')
+        print >> jsfile, self.TOGGLE_PRIVATE_JS
+        print >> jsfile, self.SHOW_PRIVATE_JS
+        print >> jsfile, self.GET_COOKIE_JS
+        print >> jsfile, self.SET_FRAME_JS
+        print >> jsfile, self.HIDE_PRIVATE_JS
+        print >> jsfile, self.TOGGLE_CALLGRAPH_JS
+        print >> jsfile, html_colorize.PYSRC_JAVASCRIPTS
+        print >> jsfile, self.GET_ANCHOR_JS
+        print >> jsfile, self.REDIRECT_URL_JS
+        jsfile.close()
+
+    #: A javascript that is used to show or hide the API documentation
+    #: for private objects.  In order for this to work correctly, all
+    #: documentation for private objects should be enclosed in 
+    #: C{<div class="private">...</div>} elements.
+    TOGGLE_PRIVATE_JS = '''
+      function toggle_private() {
+        // Search for any private/public links on this page.  Store
+        // their old text in "cmd," so we will know what action to
+        // take; and change their text to the opposite action.
+        var cmd = "?";
+        var elts = document.getElementsByTagName("a");
+        for(var i=0; i<elts.length; i++) {
+          if (elts[i].className == "privatelink") {
+            cmd = elts[i].innerHTML;
+            elts[i].innerHTML = ((cmd && cmd.substr(0,4)=="show")?
+                                    "hide&nbsp;private":"show&nbsp;private");
+          }
+        }
+        // Update all DIVs containing private objects.
+        var elts = document.getElementsByTagName("div");
+        for(var i=0; i<elts.length; i++) {
+          if (elts[i].className == "private") {
+            elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"block");
+          }
+          else if (elts[i].className == "public") {
+            elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"block":"none");
+          }
+        }
+        // Update all table rows containing private objects.  Note, we
+        // use "" instead of "block" becaue IE & firefox disagree on what
+        // this should be (block vs table-row), and "" just gives the
+        // default for both browsers.
+        var elts = document.getElementsByTagName("tr");
+        for(var i=0; i<elts.length; i++) {
+          if (elts[i].className == "private") {
+            elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"");
+          }
+        }
+        // Update all list items containing private objects.
+        var elts = document.getElementsByTagName("li");
+        for(var i=0; i<elts.length; i++) {
+          if (elts[i].className == "private") {
+            elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?
+                                        "none":"");
+          }
+        }
+        // Update all list items containing private objects.
+        var elts = document.getElementsByTagName("ul");
+        for(var i=0; i<elts.length; i++) {
+          if (elts[i].className == "private") {
+            elts[i].style.display = ((cmd && cmd.substr(0,4)=="hide")?"none":"block");
+          }
+        }
+        // Set a cookie to remember the current option.
+        document.cookie = "EpydocPrivate="+cmd;
+      }
+      '''.strip()
+
+    #: A javascript that is used to read the value of a cookie.  This
+    #: is used to remember whether private variables should be shown or
+    #: hidden.
+    GET_COOKIE_JS = '''
+      function getCookie(name) {
+        var dc = document.cookie;
+        var prefix = name + "=";
+        var begin = dc.indexOf("; " + prefix);
+        if (begin == -1) {
+          begin = dc.indexOf(prefix);
+          if (begin != 0) return null;
+        } else
+        { begin += 2; }
+        var end = document.cookie.indexOf(";", begin);
+        if (end == -1)
+        { end = dc.length; }
+        return unescape(dc.substring(begin + prefix.length, end));
+      }
+      '''.strip()
+
+    #: A javascript that is used to set the contents of two frames at
+    #: once.  This is used by the project table-of-contents frame to
+    #: set both the module table-of-contents frame and the main frame
+    #: when the user clicks on a module.
+    SET_FRAME_JS = '''
+      function setFrame(url1, url2) {
+          parent.frames[1].location.href = url1;
+          parent.frames[2].location.href = url2;
+      }
+    '''.strip()
+
+    #: A javascript that is used to hide private variables, unless
+    #: either: (a) the cookie says not to; or (b) we appear to be
+    #: linking to a private variable.
+    HIDE_PRIVATE_JS = '''
+      function checkCookie() {
+        var cmd=getCookie("EpydocPrivate");
+        if (cmd && cmd.substr(0,4)!="show" && location.href.indexOf("#_") < 0)
+            toggle_private();
+      }
+    '''.strip()
+
+    TOGGLE_CALLGRAPH_JS = '''
+      function toggleCallGraph(id) {
+        var elt = document.getElementById(id);
+        if (elt.style.display == "none")
+            elt.style.display = "block";
+        else
+            elt.style.display = "none";
+      }
+    '''.strip()
+
+    SHOW_PRIVATE_JS = '''
+      function show_private() {
+        var elts = document.getElementsByTagName("a");
+        for(var i=0; i<elts.length; i++) {
+          if (elts[i].className == "privatelink") {
+            cmd = elts[i].innerHTML;
+            if (cmd && cmd.substr(0,4)=="show")
+                toggle_private();
+          }
+        }
+      }
+    '''.strip()
+
+    GET_ANCHOR_JS = '''
+      function get_anchor() {
+          var href = location.href;
+          var start = href.indexOf("#")+1;
+          if ((start != 0) && (start != href.length))
+              return href.substring(start, href.length);
+      }
+    '''.strip()
+
+    #: A javascript that is used to implement the auto-redirect page.
+    #: When the user visits <redirect.html#dotted.name>, they will
+    #: automatically get redirected to the page for the object with
+    #: the given fully-qualified dotted name.  E.g., for epydoc,
+    #: <redirect.html#epydoc.apidoc.UNKNOWN> redirects the user to
+    #: <epydoc.apidoc-module.html#UNKNOWN>.
+    REDIRECT_URL_JS = '''
+      function redirect_url(dottedName) {
+          // Scan through each element of the "pages" list, and check
+          // if "name" matches with any of them.
+          for (var i=0; i<pages.length; i++) {
+
+              // Each page has the form "<pagename>-m" or "<pagename>-c";
+              // extract the <pagename> portion & compare it to dottedName.
+              var pagename = pages[i].substring(0, pages[i].length-2);
+              if (pagename == dottedName.substring(0,pagename.length)) {
+
+                  // We\'ve found a page that matches `dottedName`;
+                  // construct its URL, using leftover `dottedName`
+                  // content to form an anchor.
+                  var pagetype = pages[i].charAt(pages[i].length-1);
+                  var url = pagename + ((pagetype=="m")?"-module.html":
+                                                        "-class.html");
+                  if (dottedName.length > pagename.length)
+                      url += "#" + dottedName.substring(pagename.length+1,
+                                                        dottedName.length);
+                  return url;
+              }
+          }
+      }
+    '''.strip()
+          
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.10. Graphs
+    #////////////////////////////////////////////////////////////
+
+    def render_graph(self, graph):
+        if graph is None: return ''
+        graph.caption = graph.title = None
+        image_url = '%s.gif' % graph.uid
+        image_file = os.path.join(self._directory, image_url)
+        return graph.to_html(image_file, image_url)
+    
+    RE_CALLGRAPH_ID = re.compile(r"""["'](.+-div)['"]""")
+    
+    def render_callgraph(self, callgraph, token=""):
+        """Render the HTML chunk of a callgraph.
+
+        If C{callgraph} is a string, use the L{_callgraph_cache} to return
+        a pre-rendered HTML chunk. This mostly avoids to run C{dot} twice for
+        the same callgraph. Else, run the graph and store its HTML output in
+        the cache.
+
+        @param callgraph: The graph to render or its L{uid<DotGraph.uid>}.
+        @type callgraph: L{DotGraph} or C{str}
+        @param token: A string that can be used to make the C{<div>} id
+            unambiguous, if the callgraph is used more than once in a page.
+        @type token: C{str}
+        @return: The HTML representation of the graph.
+        @rtype: C{str}
+        """
+        if callgraph is None: return ""
+        
+        if isinstance(callgraph, basestring):
+            uid = callgraph
+            rv = self._callgraph_cache.get(callgraph, "")
+
+        else:
+            uid = callgraph.uid
+            graph_html = self.render_graph(callgraph)
+            if graph_html == '':
+                rv = ""
+            else:
+                rv = ('<div style="display:none" id="%%s-div"><center>\n'
+                      '<table border="0" cellpadding="0" cellspacing="0">\n'
+                      '  <tr><td>%s</td></tr>\n'
+                      '  <tr><th>Call Graph</th></tr>\n'
+                      '</table><br />\n</center></div>\n' % graph_html)
+
+            # Store in the cache the complete HTML chunk without the
+            # div id, which may be made unambiguous by the token
+            self._callgraph_cache[uid] = rv
+
+        # Mangle with the graph
+        if rv: rv = rv % (uid + token)
+        return rv
+
+    def callgraph_link(self, callgraph, token=""):
+        """Render the HTML chunk of a callgraph link.
+
+        The link can toggles the visibility of the callgraph rendered using
+        L{render_callgraph} with matching parameters.
+
+        @param callgraph: The graph to render or its L{uid<DotGraph.uid>}.
+        @type callgraph: L{DotGraph} or C{str}
+        @param token: A string that can be used to make the C{<div>} id
+            unambiguous, if the callgraph is used more than once in a page.
+        @type token: C{str}
+        @return: The HTML representation of the graph link.
+        @rtype: C{str}
+        """
+        # Use class=codelink, to match style w/ the source code link.
+        if callgraph is None: return ''
+
+        if isinstance(callgraph, basestring):
+            uid = callgraph
+        else:
+            uid = callgraph.uid
+
+        return ('<br /><span class="codelink"><a href="javascript:void(0);" '
+                'onclick="toggleCallGraph(\'%s-div\');return false;">'
+                'call&nbsp;graph</a></span>&nbsp;' % (uid + token))
+
+    #////////////////////////////////////////////////////////////
+    #{ 2.11. Images
+    #////////////////////////////////////////////////////////////
+
+    IMAGES = {'crarr.png': # Carriage-return arrow, used for LINEWRAP.
+              'iVBORw0KGgoAAAANSUhEUgAAABEAAAAKCAMAAABlokWQAAAALHRFWHRD'
+              'cmVhdGlvbiBUaW1lAFR1\nZSAyMiBBdWcgMjAwNiAwMDo0MzoxMCAtMD'
+              'UwMGAMEFgAAAAHdElNRQfWCBYFASkQ033WAAAACXBI\nWXMAAB7CAAAe'
+              'wgFu0HU+AAAABGdBTUEAALGPC/xhBQAAAEVQTFRF////zcOw18/AgGY0'
+              'c1cg4dvQ\ninJEYEAAYkME3NXI6eTcloFYe2Asr5+AbE4Uh29A9fPwqp'
+              'l4ZEUI8O3onopk0Ma0lH5U1nfFdgAA\nAAF0Uk5TAEDm2GYAAABNSURB'
+              'VHjaY2BAAbzsvDAmK5oIlxgfioiwCAe7KJKIgKAQOzsLLwTwA0VY\n+d'
+              'iRAT8T0AxuIIMHqoaXCWIPGzsHJ6orGJiYWRjQASOcBQAocgMSPKMTIg'
+              'AAAABJRU5ErkJggg==\n',
+              }
+
+    def write_images(self, directory):
+        for (name, data) in self.IMAGES.items():
+            f = open(os.path.join(directory, name), 'wb')
+            f.write(base64.decodestring(data))
+            f.close()
+
+    #////////////////////////////////////////////////////////////
+    #{ 3.1. Page Header
+    #////////////////////////////////////////////////////////////
+
+    write_header = compile_template(
+        """
+        write_header(self, out, title)
+
+        Generate HTML code for the standard page header, and write it
+        to C{out}.  C{title} is a string containing the page title.
+        It should be appropriately escaped/encoded.
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        <?xml version="1.0" encoding="ascii"?>
+        <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
+                  "DTD/xhtml1-transitional.dtd">
+        <html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
+        <head>
+          <title>$title$</title>
+          <link rel="stylesheet" href="epydoc.css" type="text/css" />
+          <script type="text/javascript" src="epydoc.js"></script>
+        </head>
+        
+        <body bgcolor="white" text="black" link="blue" vlink="#204080"
+              alink="#204080">
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ 3.2. Page Footer
+    #////////////////////////////////////////////////////////////
+
+    write_footer = compile_template(
+        """
+        write_footer(self, out, short=False)
+
+        Generate HTML code for the standard page footer, and write it
+        to C{out}.
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        >>> if not short:
+        <table border="0" cellpadding="0" cellspacing="0" width="100%%">
+          <tr>
+            <td align="left" class="footer">
+        >>>   if self._include_log:
+            <a href="epydoc-log.html">Generated by Epydoc
+            $epydoc.__version__$ on $time.asctime()$</a>
+        >>>   else:
+            Generated by Epydoc $epydoc.__version__$ on $time.asctime()$
+        >>>   #endif
+            </td>
+            <td align="right" class="footer">
+              <a target="mainFrame" href="http://epydoc.sourceforge.net"
+                >http://epydoc.sourceforge.net</a>
+            </td>
+          </tr>
+        </table>
+        >>> #endif
+
+        <script type="text/javascript">
+          <!--
+          // Private objects are initially displayed (because if
+          // javascript is turned off then we want them to be
+          // visible); but by default, we want to hide them.  So hide
+          // them unless we have a cookie that says to show them.
+          checkCookie();
+          // -->
+        </script>
+        </body>
+        </html>
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ 3.3. Navigation Bar
+    #////////////////////////////////////////////////////////////
+
+    write_navbar = compile_template(
+        """
+        write_navbar(self, out, context)
+
+        Generate HTML code for the navigation bar, and write it to
+        C{out}.  The navigation bar typically looks like::
+
+             [ Home Trees Index Help             Project ]
+
+        @param context: A value indicating what page we're generating
+        a navigation bar for.  If we're generating an API
+        documentation page for an object, then C{context} is a
+        L{ValueDoc} containing the documentation for that object;
+        otherwise, C{context} is a string name for the page.  The
+        following string names are recognized: C{'tree'}, C{'index'},
+        and C{'help'}.
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        <!-- ==================== NAVIGATION BAR ==================== -->
+        <table class="navbar" border="0" width="100%" cellpadding="0"
+               bgcolor="#a0c0ff" cellspacing="0">
+          <tr valign="middle">
+        >>> if self._top_page_url not in (self._trees_url, "identifier-index.html", "help.html"):
+          <!-- Home link -->
+        >>>   if (isinstance(context, ValueDoc) and
+        >>>       self._top_page_url == self.url(context.canonical_name)):
+              <th bgcolor="#70b0f0" class="navbar-select"
+                  >&nbsp;&nbsp;&nbsp;Home&nbsp;&nbsp;&nbsp;</th>
+        >>>   else:
+              <th>&nbsp;&nbsp;&nbsp;<a
+                href="$self._top_page_url$">Home</a>&nbsp;&nbsp;&nbsp;</th>
+        >>> #endif
+        
+          <!-- Tree link -->
+        >>> if context == "trees":
+              <th bgcolor="#70b0f0" class="navbar-select"
+                  >&nbsp;&nbsp;&nbsp;Trees&nbsp;&nbsp;&nbsp;</th>
+        >>> else:
+              <th>&nbsp;&nbsp;&nbsp;<a
+                href="$self._trees_url$">Trees</a>&nbsp;&nbsp;&nbsp;</th>
+        >>> #endif
+        
+          <!-- Index link -->
+        >>> if context == "indices":
+              <th bgcolor="#70b0f0" class="navbar-select"
+                  >&nbsp;&nbsp;&nbsp;Indices&nbsp;&nbsp;&nbsp;</th>
+        >>> else:
+              <th>&nbsp;&nbsp;&nbsp;<a
+                href="identifier-index.html">Indices</a>&nbsp;&nbsp;&nbsp;</th>
+        >>> #endif
+        
+          <!-- Help link -->
+        >>> if context == "help":
+              <th bgcolor="#70b0f0" class="navbar-select"
+                  >&nbsp;&nbsp;&nbsp;Help&nbsp;&nbsp;&nbsp;</th>
+        >>> else:
+              <th>&nbsp;&nbsp;&nbsp;<a
+                href="help.html">Help</a>&nbsp;&nbsp;&nbsp;</th>
+        >>> #endif
+        
+        >>> if self._prj_link:
+          <!-- Project homepage -->
+              <th class="navbar" align="right" width="100%">
+                <table border="0" cellpadding="0" cellspacing="0">
+                  <tr><th class="navbar" align="center"
+                    >$self._prj_link.strip()$</th>
+                  </tr></table></th>
+        >>> else:
+              <th class="navbar" width="100%"></th>
+        >>> #endif
+          </tr>
+        </table>
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ 3.4. Breadcrumbs
+    #////////////////////////////////////////////////////////////
+
+    write_breadcrumbs = compile_template(
+        """
+        write_breadcrumbs(self, out, context, context_url)
+
+        Generate HTML for the breadcrumbs line, and write it to
+        C{out}.  The breadcrumbs line is an invisible table with a
+        list of pointers to the current object's ancestors on the
+        left; and the show/hide private selector and the
+        frames/noframes selector on the right.
+
+        @param context: The API documentation for the object whose
+        breadcrumbs we should generate.
+        @type context: L{ValueDoc}
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        <table width="100%" cellpadding="0" cellspacing="0">
+          <tr valign="top">
+        >>> if isinstance(context, APIDoc):
+            <td width="100%">
+              <span class="breadcrumbs">
+        >>>   crumbs = self.breadcrumbs(context)
+        >>>   for crumb in crumbs[:-1]:
+                $crumb$ ::
+        >>>   #endfor
+                $crumbs[-1]$
+              </span>
+            </td>
+        >>> else:
+            <td width="100%">&nbsp;</td>
+        >>> #endif
+            <td>
+              <table cellpadding="0" cellspacing="0">
+                <!-- hide/show private -->
+        >>> if self._show_private:
+                <tr><td align="right">$self.PRIVATE_LINK$</td></tr>
+        >>> #endif
+        >>> if self._frames_index:
+                <tr><td align="right"><span class="options"
+                    >[<a href="frames.html" target="_top">frames</a
+                    >]&nbsp;|&nbsp;<a href="$context_url$"
+                    target="_top">no&nbsp;frames</a>]</span></td></tr>
+        >>> #endif
+              </table>
+            </td>
+          </tr>
+        </table>
+        ''')
+        # \------------------------------------------------------------/
+
+    def breadcrumbs(self, doc):
+        crumbs = [self._crumb(doc)]
+
+        # Generate the crumbs for uid's ancestors.
+        while True:
+            container = self.docindex.container(doc)
+            assert doc != container, 'object is its own container?'
+            if container is None:
+                if doc.canonical_name is UNKNOWN:
+                    return ['??']+crumbs
+                elif isinstance(doc, ModuleDoc):
+                    return ['Package&nbsp;%s' % ident
+                            for ident in doc.canonical_name[:-1]]+crumbs
+                else:
+                    return list(doc.canonical_name)+crumbs
+            else:
+                label = self._crumb(container)
+                name = container.canonical_name
+                crumbs.insert(0, self.href(container, label)) # [xx] code=0??
+                doc = container
+        
+    def _crumb(self, doc):
+        if (len(doc.canonical_name)==1 and
+            doc.canonical_name[0].startswith('script-')):
+            return 'Script&nbsp;%s' % doc.canonical_name[0][7:]
+        return '%s&nbsp;%s' % (self.doc_kind(doc), doc.canonical_name[-1])
+
+    #////////////////////////////////////////////////////////////
+    #{ 3.5. Summary Tables
+    #////////////////////////////////////////////////////////////
+
+    def write_summary_table(self, out, heading, doc, value_type):
+        """
+        Generate HTML code for a summary table, and write it to
+        C{out}.  A summary table is a table that includes a one-row
+        description for each variable (of a given type) in a module
+        or class.
+
+        @param heading: The heading for the summary table; typically,
+            this indicates what kind of value the table describes
+            (e.g., functions or classes).
+        @param doc: A L{ValueDoc} object containing the API
+            documentation for the module or class whose variables
+            we should summarize.
+        @param value_type: A string indicating what type of value
+            should be listed in this summary table.  This value
+            is passed on to C{doc}'s C{select_variables()} method.
+        """
+        # inh_var_groups is a dictionary used to hold "inheritance
+        # pseudo-groups", which are created when inheritance is
+        # 'grouped'.  It maps each base to a list of vars inherited
+        # from that base.
+        grouped_inh_vars = {}
+
+        # Divide all public variables of the given type into groups.
+        groups = [(plaintext_to_html(group_name),
+                   doc.select_variables(group=group_name, imported=False,
+                                        value_type=value_type,
+                                        public=self._public_filter))
+                  for group_name in doc.group_names()]
+                
+        # Discard any empty groups; and return if they're all empty.
+        groups = [(g,vars) for (g,vars) in groups if vars]
+        if not groups: return
+
+        # Write a header
+        self.write_table_header(out, "summary", heading)
+
+        # Write a section for each group.
+        for name, var_docs in groups:
+            self.write_summary_group(out, doc, name,
+                                     var_docs, grouped_inh_vars)
+
+        # Write a section for each inheritance pseudo-group (used if
+        # inheritance=='grouped')
+        if grouped_inh_vars:
+            for base in doc.mro():
+                if base in grouped_inh_vars:
+                    hdr = 'Inherited from %s' % self.href(base, context=doc)
+                    tr_class = ''
+                    if len([v for v in grouped_inh_vars[base]
+                            if v.is_public]) == 0:
+                        tr_class = ' class="private"'
+                    self.write_group_header(out, hdr, tr_class)
+                    for var_doc in grouped_inh_vars[base]:
+                        self.write_summary_line(out, var_doc, doc)
+
+        # Write a footer for the table.
+        out(self.TABLE_FOOTER)
+
+    def write_summary_group(self, out, doc, name, var_docs, grouped_inh_vars):
+        # Split up the var_docs list, according to the way each var
+        # should be displayed:
+        #   - listed_inh_vars -- for listed inherited variables.
+        #   - grouped_inh_vars -- for grouped inherited variables.
+        #   - normal_vars -- for all other variables.
+        listed_inh_vars = {}
+        normal_vars = []
+        for var_doc in var_docs:
+            if var_doc.container != doc:
+                base = var_doc.container
+                if not isinstance(base, ClassDoc):
+                    # This *should* never happen:
+                    log.warning("%s's container is not a class!" % var_doc)
+                    normal_vars.append(var_doc)
+                elif (base not in self.class_set or
+                    self._inheritance == 'listed'):
+                    listed_inh_vars.setdefault(base,[]).append(var_doc)
+                elif self._inheritance == 'grouped':
+                    grouped_inh_vars.setdefault(base,[]).append(var_doc)
+                else:
+                    normal_vars.append(var_doc)
+            else:
+                normal_vars.append(var_doc)
+            
+        # Write a header for the group.
+        if name != '':
+            tr_class = ''
+            if len([v for v in var_docs if v.is_public]) == 0:
+                tr_class = ' class="private"'
+            self.write_group_header(out, name, tr_class)
+
+        # Write a line for each normal var:
+        for var_doc in normal_vars:
+            self.write_summary_line(out, var_doc, doc)
+        # Write a subsection for inherited vars:
+        if listed_inh_vars:
+            self.write_inheritance_list(out, doc, listed_inh_vars)
+
+    def write_inheritance_list(self, out, doc, listed_inh_vars):
+        out('  <tr>\n    <td colspan="2" class="summary">\n')
+        for base in doc.mro():
+            if base not in listed_inh_vars: continue
+            public_vars = [v for v in listed_inh_vars[base]
+                           if v.is_public]
+            private_vars = [v for v in listed_inh_vars[base]
+                            if not v.is_public]
+            if public_vars:
+                out('    <p class="indent-wrapped-lines">'
+                    '<b>Inherited from <code>%s</code></b>:\n' %
+                    self.href(base, context=doc))
+                self.write_var_list(out, public_vars)
+                out('      </p>\n')
+            if private_vars and self._show_private:
+                out('    <div class="private">')
+                out('    <p class="indent-wrapped-lines">'
+                    '<b>Inherited from <code>%s</code></b> (private):\n' %
+                    self.href(base, context=doc))
+                self.write_var_list(out, private_vars)
+                out('      </p></div>\n')
+        out('    </td>\n  </tr>\n')
+    
+    def write_var_list(self, out, vardocs):
+        out('      ')
+        out(',\n      '.join(['<code>%s</code>' % self.href(v,v.name)
+                              for v in vardocs])+'\n')
+
+    def write_summary_line(self, out, var_doc, container):
+        """
+        Generate HTML code for a single line of a summary table, and
+        write it to C{out}.  See L{write_summary_table} for more
+        information.
+        
+        @param var_doc: The API documentation for the variable that
+            should be described by this line of the summary table.
+        @param container: The API documentation for the class or
+            module whose summary table we're writing.
+        """
+        pysrc_link = None
+        callgraph = None
+
+        # If it's a private variable, then mark its <tr>.
+        if var_doc.is_public: tr_class = ''
+        else: tr_class = ' class="private"'
+
+        # Decide an anchor or a link is to be generated.
+        link_name = self._redundant_details or var_doc.is_detailed()
+        anchor = not link_name
+
+        # Construct the HTML code for the type (cell 1) & description
+        # (cell 2).
+        if isinstance(var_doc.value, RoutineDoc):
+            typ = self.return_type(var_doc, indent=6)
+            description = self.function_signature(var_doc, is_summary=True,
+                link_name=link_name, anchor=anchor)
+            pysrc_link = self.pysrc_link(var_doc.value)
+
+            # Perpare the call-graph, if requested
+            if 'callgraph' in self._graph_types:
+                linker = _HTMLDocstringLinker(self, var_doc.value)
+                callgraph = call_graph([var_doc.value], self.docindex,
+                                       linker, var_doc, add_callers=True, 
+                                       add_callees=True)
+                if callgraph and callgraph.nodes:
+                    var_doc.value.callgraph_uid = callgraph.uid
+                else:
+                    callgraph = None
+        else:
+            typ = self.type_descr(var_doc, indent=6)
+            description = self.summary_name(var_doc,
+                link_name=link_name, anchor=anchor)
+            if isinstance(var_doc.value, GenericValueDoc):
+                # The summary max length has been chosen setting
+                # L{ValueDoc.SUMMARY_REPR_LINELEN} in the constructor
+                max_len=self._variable_summary_linelen-3-len(var_doc.name)
+                val_repr = var_doc.value.summary_pyval_repr(max_len)
+                tooltip = self.variable_tooltip(var_doc)
+                description += (' = <code%s>%s</code>' %
+                                (tooltip, val_repr.to_html(None)))
+
+        # Add the summary to the description (if there is one).
+        summary = self.summary(var_doc, indent=6)
+        if summary: description += '<br />\n      %s' % summary
+        
+        # If it's inherited, then add a note to the description.
+        if var_doc.container != container and self._inheritance=="included":
+            description += ("\n      <em>(Inherited from " +
+                        self.href(var_doc.container) + ")</em>")
+
+        # Write the summary line.
+        self._write_summary_line(out, typ, description, tr_class, pysrc_link,
+                                 callgraph)
+
+    _write_summary_line = compile_template(
+        "_write_summary_line(self, out, typ, description, tr_class, "
+                            "pysrc_link, callgraph)",
+        # /------------------------- Template -------------------------\
+        '''
+          <tr$tr_class$>
+            <td width="15%" align="right" valign="top" class="summary">
+              <span class="summary-type">$typ or "&nbsp;"$</span>
+            </td><td class="summary">
+        >>> if pysrc_link is not None or callgraph is not None:
+              <table width="100%" cellpadding="0" cellspacing="0" border="0">
+                <tr>
+                  <td>$description$</td>
+                  <td align="right" valign="top">
+                    $pysrc_link$
+                    $self.callgraph_link(callgraph, token='-summary')$
+                  </td>
+                </tr>
+              </table>
+              $self.render_callgraph(callgraph, token='-summary')$
+        >>> #endif
+        >>> if pysrc_link is None and callgraph is None:
+                $description$
+        >>> #endif
+            </td>
+          </tr>
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ 3.6. Details Lists
+    #////////////////////////////////////////////////////////////
+
+    def write_details_list(self, out, heading, doc, value_type):
+        # Get a list of the VarDocs we should describe.
+        if self._redundant_details:
+            detailed = None
+        else:
+            detailed = True
+        if isinstance(doc, ClassDoc):
+            var_docs = doc.select_variables(value_type=value_type,
+                                            imported=False, inherited=False,
+                                            public=self._public_filter,
+                                            detailed=detailed)
+        else:
+            var_docs = doc.select_variables(value_type=value_type,
+                                            imported=False,
+                                            public=self._public_filter,
+                                            detailed=detailed)
+        if not var_docs: return
+
+        # Write a header
+        self.write_table_header(out, "details", heading)
+        out(self.TABLE_FOOTER)
+
+        for var_doc in var_docs:
+            self.write_details_entry(out, var_doc)
+
+        out('<br />\n')
+
+    def write_details_entry(self, out, var_doc):
+        descr = self.descr(var_doc, indent=2) or ''
+        if var_doc.is_public: div_class = ''
+        else: div_class = ' class="private"'
+
+        # Functions
+        if isinstance(var_doc.value, RoutineDoc):
+            rtype = self.return_type(var_doc, indent=10)
+            rdescr = self.return_descr(var_doc, indent=10)
+            arg_descrs = []
+            args = set()
+            # Find the description for each arg.  (Leave them in the
+            # same order that they're listed in the docstring.)
+            for (arg_names, arg_descr) in var_doc.value.arg_descrs:
+                args.update(arg_names)
+                lhs = ', '.join([self.arg_name_to_html(var_doc.value, n)
+                                 for n in arg_names])
+                rhs = self.docstring_to_html(arg_descr, var_doc.value, 10)
+                arg_descrs.append( (lhs, rhs) )
+            # Check for arguments for which we have @type but not @param;
+            # and add them to the arg_descrs list.
+            for arg in var_doc.value.arg_types:
+                if arg not in args:
+                    argname = self.arg_name_to_html(var_doc.value, arg)
+                    arg_descrs.append( (argname,'') )
+
+            self.write_function_details_entry(out, var_doc, descr,
+                                              var_doc.value.callgraph_uid,
+                                              rtype, rdescr, arg_descrs,
+                                              div_class)
+
+        # Properties
+        elif isinstance(var_doc.value, PropertyDoc):
+            prop_doc = var_doc.value
+            accessors = [ (name,
+                           self.property_accessor_to_html(val_doc, prop_doc),
+                           self.summary(val_doc))
+                         for (name, val_doc) in
+                            [('Get', prop_doc.fget), ('Set', prop_doc.fset),
+                             ('Delete', prop_doc.fdel)]
+                            if val_doc not in (None, UNKNOWN)
+                            and val_doc.pyval is not None ]
+
+            self.write_property_details_entry(out, var_doc, descr,
+                                              accessors, div_class)
+        
+        # Variables
+        else:
+            self.write_variable_details_entry(out, var_doc, descr, div_class)
+
+    def labelled_list_item(self, lhs, rhs):
+        # If the RHS starts with a paragraph, then move the
+        # paragraph-start tag to the beginning of the lhs instead (so
+        # there won't be a line break after the '-').
+        m = re.match(r'^<p( [^>]+)?>', rhs)
+        if m:
+            lhs = m.group() + lhs
+            rhs = rhs[m.end():]
+
+        if rhs:
+            return '<li>%s - %s</li>' % (lhs, rhs)
+        else:
+            return '<li>%s</li>' % (lhs,)
+
+    def property_accessor_to_html(self, val_doc, context=None):
+        if val_doc not in (None, UNKNOWN):
+            if isinstance(val_doc, RoutineDoc):
+                return self.function_signature(val_doc, is_summary=True,
+                                               link_name=True, context=context)
+            elif isinstance(val_doc, GenericValueDoc):
+                return self.pprint_value(val_doc)
+            else:
+                return self.href(val_doc, context=context)
+        else:
+            return '??'
+        
+    def arg_name_to_html(self, func_doc, arg_name):
+        """
+        A helper function used to format an argument name, for use in
+        the argument description list under a routine's details entry.
+        This just wraps strong & code tags around the arg name; and if
+        the arg name is associated with a type, then adds it
+        parenthetically after the name.
+        """
+        s = '<strong class="pname"><code>%s</code></strong>' % arg_name
+        if arg_name in func_doc.arg_types:
+            typ = func_doc.arg_types[arg_name]
+            typ_html = self.docstring_to_html(typ, func_doc, 10)
+            s += " (%s)" % typ_html
+        return s
+
+    write_function_details_entry = compile_template(
+        '''
+        write_function_details_entry(self, out, var_doc, descr, callgraph, \
+                                     rtype, rdescr, arg_descrs, div_class)
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        >>> func_doc = var_doc.value
+        <a name="$var_doc.name$"></a>
+        <div$div_class$>
+        >>> self.write_table_header(out, "details")
+        <tr><td>
+          <table width="100%" cellpadding="0" cellspacing="0" border="0">
+          <tr valign="top"><td>
+          <h3 class="epydoc">$self.function_signature(var_doc)$
+        >>> if var_doc.name in self.SPECIAL_METHODS:
+            <br /><em class="fname">($self.SPECIAL_METHODS[var_doc.name]$)</em>
+        >>> #endif
+        >>> if isinstance(func_doc, ClassMethodDoc):
+            <br /><em class="fname">Class Method</em>
+        >>> #endif
+        >>> if isinstance(func_doc, StaticMethodDoc):
+            <br /><em class="fname">Static Method</em>
+        >>> #endif
+          </h3>
+          </td><td align="right" valign="top"
+            >$self.pysrc_link(func_doc)$&nbsp;
+            $self.callgraph_link(callgraph)$</td>
+          </tr></table>
+          $self.render_callgraph(callgraph)$
+          $descr$
+          <dl class="fields">
+        >>> # === parameters ===
+        >>> if arg_descrs:
+            <dt>Parameters:</dt>
+            <dd><ul class="nomargin-top">
+        >>>   for lhs, rhs in arg_descrs:
+                $self.labelled_list_item(lhs, rhs)$
+        >>>   #endfor
+            </ul></dd>
+        >>> #endif
+        >>> # === return type ===
+        >>> if rdescr and rtype:
+            <dt>Returns: $rtype$</dt>
+                <dd>$rdescr$</dd>
+        >>> elif rdescr:
+            <dt>Returns:</dt>
+                <dd>$rdescr$</dd>
+        >>> elif rtype:
+            <dt>Returns: $rtype$</dt>
+        >>> #endif
+        >>> # === decorators ===
+        >>> if func_doc.decorators not in (None, UNKNOWN):
+        >>>   # (staticmethod & classmethod are already shown, above)
+        >>>   decos = filter(lambda deco:
+        >>>     not ((deco=="staticmethod" and
+        >>>            isinstance(func_doc, StaticMethodDoc)) or
+        >>>          (deco=="classmethod" and
+        >>>           isinstance(func_doc, ClassMethodDoc))),
+        >>>     func_doc.decorators)
+        >>> else:
+        >>>   decos = None
+        >>> #endif
+        >>> if decos:
+            <dt>Decorators:</dt>
+            <dd><ul class="nomargin-top">
+        >>>   for deco in decos:
+                <li><code>@$deco$</code></li>
+        >>>   #endfor
+            </ul></dd>
+        >>> #endif
+        >>> # === exceptions ===
+        >>> if func_doc.exception_descrs not in (None, UNKNOWN, (), []):
+            <dt>Raises:</dt>
+            <dd><ul class="nomargin-top">
+        >>>   for name, descr in func_doc.exception_descrs:
+        >>>     exc_name = self.docindex.find(name, func_doc)
+        >>>     if exc_name is not None:
+        >>>       name = self.href(exc_name, label=str(name))
+        >>>     #endif
+                $self.labelled_list_item(
+                    "<code><strong class=\'fraise\'>" +
+                    str(name) + "</strong></code>",
+                    self.docstring_to_html(descr, func_doc, 8))$
+        >>>   #endfor
+            </ul></dd>
+        >>> #endif
+        >>> # === overrides ===
+        >>> if var_doc.overrides not in (None, UNKNOWN):
+            <dt>Overrides:
+        >>>   # Avoid passing GenericValueDoc to href()
+        >>>   if isinstance(var_doc.overrides.value, RoutineDoc):
+                $self.href(var_doc.overrides.value, context=var_doc)$
+        >>>   else:
+        >>>     # In this case, a less interesting label is generated.
+                $self.href(var_doc.overrides, context=var_doc)$
+        >>>   #endif
+        >>>   if (func_doc.docstring in (None, UNKNOWN) and
+        >>>       var_doc.overrides.value.docstring not in (None, UNKNOWN)):
+                <dd><em class="note">(inherited documentation)</em></dd>
+        >>>   #endif
+            </dt>
+        >>> #endif
+          </dl>
+        >>> # === metadata ===
+        >>> self.write_standard_fields(out, func_doc)
+        </td></tr></table>
+        </div>
+        ''')
+        # \------------------------------------------------------------/
+
+    # Names for the __special__ methods.
+    SPECIAL_METHODS ={
+    '__init__': 'Constructor',
+    '__del__': 'Destructor',
+    '__add__': 'Addition operator',
+    '__sub__': 'Subtraction operator',
+    '__and__': 'And operator',
+    '__or__': 'Or operator',
+    '__xor__': 'Exclusive-Or operator',
+    '__repr__': 'Representation operator',
+    '__call__': 'Call operator',
+    '__getattr__': 'Qualification operator',
+    '__getitem__': 'Indexing operator',
+    '__setitem__': 'Index assignment operator',
+    '__delitem__': 'Index deletion operator',
+    '__delslice__': 'Slice deletion operator',
+    '__setslice__': 'Slice assignment operator',
+    '__getslice__': 'Slicling operator',
+    '__len__': 'Length operator',
+    '__cmp__': 'Comparison operator',
+    '__eq__': 'Equality operator',
+    '__in__': 'Containership operator',
+    '__gt__': 'Greater-than operator',
+    '__lt__': 'Less-than operator',
+    '__ge__': 'Greater-than-or-equals operator',
+    '__le__': 'Less-than-or-equals operator',
+    '__radd__': 'Right-side addition operator',
+    '__hash__': 'Hashing function',
+    '__contains__': 'In operator',
+    '__nonzero__': 'Boolean test operator',
+    '__str__': 'Informal representation operator',
+    }
+
+    write_property_details_entry = compile_template(
+        '''
+        write_property_details_entry(self, out, var_doc, descr, \
+                                     accessors, div_class)
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        >>> prop_doc = var_doc.value
+        <a name="$var_doc.name$"></a>
+        <div$div_class$>
+        >>> self.write_table_header(out, "details")
+        <tr><td>
+          <h3 class="epydoc">$var_doc.name$</h3>
+          $descr$
+          <dl class="fields">
+        >>> for (name, val, summary) in accessors:
+            <dt>$name$ Method:</dt>
+            <dd class="value">$val$
+        >>>     if summary:
+                - $summary$
+        >>>     #endif
+            </dd>
+        >>> #endfor
+        >>> if prop_doc.type_descr not in (None, UNKNOWN):
+            <dt>Type:</dt>
+              <dd>$self.type_descr(var_doc, indent=6)$</dd>
+        >>> #endif
+          </dl>
+        >>> self.write_standard_fields(out, prop_doc)
+        </td></tr></table>
+        </div>
+        ''')
+        # \------------------------------------------------------------/
+        
+    write_variable_details_entry = compile_template(
+        '''
+        write_variable_details_entry(self, out, var_doc, descr, div_class)
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        <a name="$var_doc.name$"></a>
+        <div$div_class$>
+        >>> self.write_table_header(out, "details")
+        <tr><td>
+          <h3 class="epydoc">$var_doc.name$</h3>
+          $descr$
+          <dl class="fields">
+        >>> if var_doc.type_descr not in (None, UNKNOWN):
+            <dt>Type:</dt>
+              <dd>$self.type_descr(var_doc, indent=6)$</dd>
+        >>> #endif
+          </dl>
+        >>> self.write_standard_fields(out, var_doc)
+        >>> if var_doc.value is not UNKNOWN:
+          <dl class="fields">
+            <dt>Value:</dt>
+              <dd>$self.pprint_value(var_doc.value)$</dd>
+          </dl>
+        >>> #endif
+        </td></tr></table>
+        </div>
+        ''')
+        # \------------------------------------------------------------/
+
+    def variable_tooltip(self, var_doc):
+        if var_doc.value in (None, UNKNOWN):
+            return ''
+        s = var_doc.value.pyval_repr().to_plaintext(None)
+        if len(s) > self._variable_tooltip_linelen:
+            s = s[:self._variable_tooltip_linelen-3]+'...'
+        return ' title="%s"' % plaintext_to_html(s)
+
+    def pprint_value(self, val_doc):
+        if val_doc is UNKNOWN:
+            return '??'
+        elif isinstance(val_doc, GenericValueDoc):
+            return ('<table><tr><td><pre class="variable">\n' +
+                    val_doc.pyval_repr().to_html(None) +
+                    '\n</pre></td></tr></table>\n')
+        else:
+            return self.href(val_doc)
+
+    #////////////////////////////////////////////////////////////
+    #{ Base Tree
+    #////////////////////////////////////////////////////////////
+
+    def base_tree(self, doc, width=None, postfix='', context=None):
+        """
+        @return: The HTML code for a class's base tree.  The tree is
+            drawn 'upside-down' and right justified, to allow for
+            multiple inheritance.
+        @rtype: C{string}
+        """
+        if context is None:
+            context = doc.defining_module
+        if width == None: width = self.find_tree_width(doc, context)
+        if isinstance(doc, ClassDoc) and doc.bases != UNKNOWN:
+            bases = doc.bases
+        else:
+            bases = []
+        
+        if postfix == '':
+            # [XX] use var name instead of canonical name?
+            s = (' '*(width-2) + '<strong class="uidshort">'+
+                   self.contextual_label(doc, context)+'</strong>\n')
+        else: s = ''
+        for i in range(len(bases)-1, -1, -1):
+            base = bases[i]
+            label = self.contextual_label(base, context)
+            s = (' '*(width-4-len(label)) + self.href(base, label)
+                   +' --+'+postfix+'\n' + 
+                   ' '*(width-4) +
+                   '   |'+postfix+'\n' +
+                   s)
+            if i != 0:
+                s = (self.base_tree(base, width-4, '   |'+postfix, context)+s)
+            else:
+                s = (self.base_tree(base, width-4, '    '+postfix, context)+s)
+        return s
+
+    def find_tree_width(self, doc, context):
+        """
+        Helper function for L{base_tree}.
+        @return: The width of a base tree, when drawn
+            right-justified.  This is used by L{base_tree} to
+            determine how far to indent lines of the base tree.
+        @rtype: C{int}
+        """
+        if not isinstance(doc, ClassDoc): return 2
+        if doc.bases == UNKNOWN: return 2
+        width = 2
+        for base in doc.bases:
+            width = max(width, len(self.contextual_label(base, context))+4,
+                        self.find_tree_width(base, context)+4)
+        return width
+
+    def contextual_label(self, doc, context):
+        """
+        Return the label for C{doc} to be shown in C{context}.
+        """
+        if doc.canonical_name is None:
+            if doc.parse_repr is not None:
+                return doc.parse_repr
+            else:
+                return '??'
+        else:
+            if context is UNKNOWN:
+                return str(doc.canonical_name)
+            else:
+                context_name = context.canonical_name
+                return str(doc.canonical_name.contextualize(context_name))
+        
+    #////////////////////////////////////////////////////////////
+    #{ Function Signatures
+    #////////////////////////////////////////////////////////////
+
+    def function_signature(self, api_doc, is_summary=False, 
+                           link_name=False, anchor=False, context=None):
+        """Render a function signature in HTML.
+
+        @param api_doc: The object whose name is to be rendered. If a
+            C{VariableDoc}, its C{value} should be a C{RoutineDoc}
+        @type api_doc: L{VariableDoc} or L{RoutineDoc}
+        @param is_summary: True if the fuction is to be rendered in the summary.
+        type css_class: C{bool}
+        @param link_name: If True, the name is a link to the object anchor.
+        @type link_name: C{bool}
+        @param anchor: If True, the name is the object anchor.
+        @type anchor: C{bool}
+        @param context: If set, represent the function name from this context.
+            Only useful when C{api_doc} is a L{RoutineDoc}.
+        @type context: L{DottedName}
+
+        @return: The HTML code for the object.
+        @rtype: C{str}
+        """
+        if is_summary: css_class = 'summary-sig'
+        else: css_class = 'sig'
+        
+        # [XX] clean this up!
+        if isinstance(api_doc, VariableDoc):
+            func_doc = api_doc.value
+            # This should never happen, but just in case:
+            if api_doc.value in (None, UNKNOWN):
+                return (('<span class="%s"><span class="%s-name">%s'+
+                         '</span>(...)</span>') %
+                        (css_class, css_class, api_doc.name))
+            # Get the function's name.
+            name = self.summary_name(api_doc, css_class=css_class+'-name',
+                                     link_name=link_name, anchor=anchor)
+        else:
+            func_doc = api_doc
+            name = self.href(api_doc, css_class=css_class+'-name',
+                             context=context)
+
+        if func_doc.posargs == UNKNOWN:
+            args = ['...']
+        else:
+            args = [self.func_arg(n, d, css_class) for (n, d)
+                    in zip(func_doc.posargs, func_doc.posarg_defaults)]
+        if func_doc.vararg not in (None, UNKNOWN):
+            if func_doc.vararg == '...':
+                args.append('<span class="%s-arg">...</span>' % css_class)
+            else:
+                args.append('<span class="%s-arg">*%s</span>' %
+                            (css_class, func_doc.vararg))
+        if func_doc.kwarg not in (None, UNKNOWN):
+            args.append('<span class="%s-arg">**%s</span>' %
+                        (css_class, func_doc.kwarg))
+
+        return ('<span class="%s">%s(%s)</span>' %
+                (css_class, name, ',\n        '.join(args)))
+
+    def summary_name(self, api_doc, css_class='summary-name',
+                     link_name=False, anchor=False):
+        """Render an object name in HTML.
+
+        @param api_doc: The object whose name is to be rendered
+        @type api_doc: L{APIDoc}
+        @param css_class: The CSS class to assign to the rendered name
+        type css_class: C{str}
+        @param link_name: If True, the name is a link to the object anchor.
+        @type link_name: C{bool}
+        @param anchor: If True, the name is the object anchor.
+        @type anchor: C{bool}
+
+        @return: The HTML code for the object.
+        @rtype: C{str}
+        """
+        if anchor:
+            rv = '<a name="%s"></a>' % api_doc.name
+        else:
+            rv = ''
+
+        if link_name:
+            rv += self.href(api_doc, css_class=css_class)
+        else:
+            rv += '<span class="%s">%s</span>' % (css_class, api_doc.name)
+
+        return rv
+
+    # [xx] tuple args???
+    def func_arg(self, name, default, css_class):
+        name = self._arg_name(name)
+        s = '<span class="%s-arg">%s</span>' % (css_class, name)
+        if default is not None:
+            s += ('=<span class="%s-default">%s</span>' %
+                    (css_class, default.summary_pyval_repr().to_html(None)))
+        return s
+
+    def _arg_name(self, arg):
+        if isinstance(arg, basestring):
+            return arg
+        elif len(arg) == 1:
+            return '(%s,)' % self._arg_name(arg[0])
+        else:
+            return '(%s)' % (', '.join([self._arg_name(a) for a in arg]))
+
+
+    
+
+    #////////////////////////////////////////////////////////////
+    #{ Import Lists
+    #////////////////////////////////////////////////////////////
+        
+    def write_imports(self, out, doc):
+        assert isinstance(doc, NamespaceDoc)
+        imports = doc.select_variables(imported=True,
+                                       public=self._public_filter)
+        if not imports: return
+
+        out('<p class="indent-wrapped-lines">')
+        out('<b>Imports:</b>\n  ')
+        out(',\n  '.join([self._import(v, doc) for v in imports]))
+        out('\n</p><br />\n')
+
+    def _import(self, var_doc, context):
+        if var_doc.imported_from not in (None, UNKNOWN):
+            return self.href(var_doc.imported_from,
+                             var_doc.name, context=context,
+                             tooltip='%s' % var_doc.imported_from)
+        elif (var_doc.value not in (None, UNKNOWN) and not
+              isinstance(var_doc.value, GenericValueDoc)):
+            return self.href(var_doc.value,
+                             var_doc.name, context=context,
+                             tooltip='%s' % var_doc.value.canonical_name)
+        else:
+            return plaintext_to_html(var_doc.name)
+            
+    #////////////////////////////////////////////////////////////
+    #{ Function Attributes
+    #////////////////////////////////////////////////////////////
+        
+    #////////////////////////////////////////////////////////////
+    #{ Module Trees
+    #////////////////////////////////////////////////////////////
+
+    def write_module_list(self, out, doc):
+        if len(doc.submodules) == 0: return
+        self.write_table_header(out, "summary", "Submodules")
+
+        for group_name in doc.group_names():
+            if not doc.submodule_groups[group_name]: continue
+            if group_name:
+                self.write_group_header(out, group_name)
+            out('  <tr><td class="summary">\n'
+                '  <ul class="nomargin">\n')
+            for submodule in doc.submodule_groups[group_name]:
+                self.write_module_tree_item(out, submodule, package=doc)
+            out('  </ul></td></tr>\n')
+                
+        out(self.TABLE_FOOTER+'\n<br />\n')
+
+    def write_module_tree_item(self, out, doc, package=None):
+        # If it's a private variable, then mark its <li>.
+        var = package and package.variables.get(doc.canonical_name[-1])
+        priv = ((var is not None and var.is_public is False) or
+                (var is None and doc.canonical_name[-1].startswith('_')))
+        out('    <li%s> <strong class="uidlink">%s</strong>'
+            % (priv and ' class="private"' or '', self.href(doc)))
+        if doc.summary not in (None, UNKNOWN):
+            out(': <em class="summary">'+
+                self.description(doc.summary, doc, 8)+'</em>')
+        if doc.submodules != UNKNOWN and doc.submodules:
+            if priv: out('\n    <ul class="private">\n')
+            else: out('\n    <ul>\n')
+            for submodule in doc.submodules:
+                self.write_module_tree_item(out, submodule, package=doc)
+            out('    </ul>\n')
+        out('    </li>\n')
+
+    #////////////////////////////////////////////////////////////
+    #{ Class trees
+    #////////////////////////////////////////////////////////////
+
+    write_class_tree_item = compile_template(
+        '''
+        write_class_tree_item(self, out, doc, class_set)
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        >>> if doc.summary in (None, UNKNOWN):
+            <li> <strong class="uidlink">$self.href(doc)$</strong>
+        >>> else:
+            <li> <strong class="uidlink">$self.href(doc)$</strong>:
+              <em class="summary">$self.description(doc.summary, doc, 8)$</em>
+        >>> # endif
+        >>> if doc.subclasses:
+            <ul>
+        >>>   for subclass in sorted(set(doc.subclasses), key=lambda c:c.canonical_name[-1]):
+        >>>     if subclass in class_set:
+        >>>       self.write_class_tree_item(out, subclass, class_set)
+        >>>     #endif
+        >>>   #endfor
+            </ul>
+        >>> #endif
+            </li>
+        ''')
+        # \------------------------------------------------------------/
+    
+    #////////////////////////////////////////////////////////////
+    #{ Standard Fields
+    #////////////////////////////////////////////////////////////
+
+    def write_standard_fields(self, out, doc):
+        """
+        Write HTML code containing descriptions of any standard markup
+        fields that are defined by the given L{APIDoc} object (such as
+        C{@author} and C{@todo} fields).
+
+        @param doc: The L{APIDoc} object containing the API documentation
+            for the object whose standard markup fields should be
+            described.
+        """
+        fields = []
+        field_values = {}
+        
+        for (field, arg, descr) in doc.metadata:
+            if field not in field_values:
+                fields.append(field)
+            if field.takes_arg:
+                subfields = field_values.setdefault(field,{})
+                subfields.setdefault(arg,[]).append(descr)
+            else:
+                field_values.setdefault(field,[]).append(descr)
+
+        if not fields: return
+
+        out('<div class="fields">')
+        for field in fields:
+            if field.takes_arg:
+                for arg, descrs in field_values[field].items():
+                    self.write_standard_field(out, doc, field, descrs, arg)
+                                              
+            else:
+                self.write_standard_field(out, doc, field, field_values[field])
+
+        out('</div>')
+
+    write_standard_field = compile_template(
+        """
+        write_standard_field(self, out, doc, field, descrs, arg='')
+        
+        """,
+        # /------------------------- Template -------------------------\
+        '''
+        >>> if arg: arglabel = " (%s)" % arg
+        >>> else: arglabel = ""
+        >>>   if len(descrs) == 1:
+              <p><strong>$field.singular+arglabel$:</strong>
+                $self.description(descrs[0], doc, 8)$
+              </p>
+        >>>   elif field.short:
+              <dl><dt>$field.plural+arglabel$:</dt>
+                <dd>
+        >>>     for descr in descrs[:-1]:
+                  $self.description(descr, doc, 10)$,
+        >>>     # end for
+                  $self.description(descrs[-1], doc, 10)$
+                </dd>
+              </dl>
+        >>>   else:
+              <strong>$field.plural+arglabel$:</strong>
+              <ul class="nomargin-top">
+        >>>     for descr in descrs:
+                <li>
+                $self.description(descr, doc, 8)$
+                </li>
+        >>>     # end for
+              </ul>
+        >>>   # end else
+        >>> # end for
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ Index generation
+    #////////////////////////////////////////////////////////////
+
+    #: A list of metadata indices that should be generated.  Each
+    #: entry in this list is a tuple C{(tag, label, short_label)},
+    #: where C{tag} is the cannonical tag of a metadata field;
+    #: C{label} is a label for the index page; and C{short_label}
+    #: is a shorter label, used in the index selector.
+    METADATA_INDICES = [('bug', 'Bug List', 'Bugs'),
+                        ('todo', 'To Do List', 'To Do'),
+                        ('change', 'Change Log', 'Changes'),
+                        ('deprecated', 'Deprecation List', 'Deprecations'),
+                        ('since', 'Introductions List', 'Introductions'),
+                        ]
+    
+    def build_identifier_index(self):
+        items = []
+        for doc in self.indexed_docs:
+            name = plaintext_to_html(doc.canonical_name[-1])
+            if isinstance(doc, RoutineDoc): name += '()'
+            url = self.url(doc)
+            if not url: continue
+            container = self.docindex.container(doc)
+            items.append( (name, url, container) )
+        return sorted(items, key=lambda v:v[0].lower())
+
+    def _group_by_letter(self, items):
+        """Preserves sort order of the input."""
+        index = {}
+        for item in items:
+            first_letter = item[0][0].upper()
+            if not ("A" <= first_letter <= "Z"):
+                first_letter = '_'
+            index.setdefault(first_letter, []).append(item)
+        return index
+    
+    def build_term_index(self):
+        items = []
+        for doc in self.indexed_docs:
+            url = self.url(doc)
+            items += self._terms_from_docstring(url, doc, doc.descr)
+            for (field, arg, descr) in doc.metadata:
+                items += self._terms_from_docstring(url, doc, descr)
+                if hasattr(doc, 'type_descr'):
+                    items += self._terms_from_docstring(url, doc,
+                                                        doc.type_descr)
+                if hasattr(doc, 'return_descr'):
+                    items += self._terms_from_docstring(url, doc,
+                                                        doc.return_descr)
+                if hasattr(doc, 'return_type'):
+                    items += self._terms_from_docstring(url, doc,
+                                                        doc.return_type)
+        return sorted(items, key=lambda v:v[0].lower())
+
+    def _terms_from_docstring(self, base_url, container, parsed_docstring):
+        if parsed_docstring in (None, UNKNOWN): return []
+        terms = []
+        # Strip any existing anchor off:
+        base_url = re.sub('#.*', '', '%s' % (base_url,))
+        for term in parsed_docstring.index_terms():
+            anchor = self._term_index_to_anchor(term)
+            url = '%s#%s' % (base_url, anchor)
+            terms.append( (term.to_plaintext(None), url, container) )
+        return terms
+
+    def build_metadata_index(self, field_name):
+        # Build the index.
+        index = {}
+        for doc in self.indexed_docs:
+            if (not self._show_private and
+                self._doc_or_ancestor_is_private(doc)):
+                continue
+            descrs = {}
+            if doc.metadata is not UNKNOWN:
+                for (field, arg, descr) in doc.metadata:
+                    if field.tags[0] == field_name:
+                        descrs.setdefault(arg, []).append(descr)
+            for (arg, descr_list) in descrs.iteritems():
+                index.setdefault(arg, []).append( (doc, descr_list) )
+        return index
+
+    def _term_index_to_anchor(self, term):
+        """
+        Given the name of an inline index item, construct a URI anchor.
+        These anchors are used to create links from the index page to each
+        index item.
+        """
+        # Include "-" so we don't accidentally collide with the name
+        # of a python identifier.
+        s = re.sub(r'\s\s+', '-', term.to_plaintext(None))
+        return "index-"+re.sub("[^a-zA-Z0-9]", "_", s)
+
+    #////////////////////////////////////////////////////////////
+    #{ Redirect page
+    #////////////////////////////////////////////////////////////
+
+    def write_redirect_page(self, out):
+        """
+        Build the auto-redirect page, which translates dotted names to
+        URLs using javascript.  When the user visits
+        <redirect.html#dotted.name>, they will automatically get
+        redirected to the page for the object with the given
+        fully-qualified dotted name.  E.g., for epydoc,
+        <redirect.html#epydoc.apidoc.UNKNOWN> redirects the user to
+        <epydoc.apidoc-module.html#UNKNOWN>.
+        """
+        # Construct a list of all the module & class pages that we're
+        # documenting.  The redirect_url javascript will scan through
+        # this list, looking for a page name that matches the
+        # requested dotted name.
+        pages = (['%s-m' % val_doc.canonical_name
+                  for val_doc in self.module_list] +
+                 ['%s-c' % val_doc.canonical_name
+                  for val_doc in self.class_list])
+        # Sort the pages from longest to shortest.  This ensures that
+        # we find e.g. "x.y.z" in the list before "x.y".
+        pages = sorted(pages, key=lambda p:-len(p))
+
+        # Write the redirect page.
+        self._write_redirect_page(out, pages)
+
+    _write_redirect_page = compile_template(
+        '''
+        _write_redirect_page(self, out, pages)
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        <html><head><title>Epydoc Redirect Page</title>
+        <meta http-equiv="cache-control" content="no-cache" />
+        <meta http-equiv="expires" content="0" />
+        <meta http-equiv="pragma" content="no-cache" />
+          <script type="text/javascript" src="epydoc.js"></script>
+        </head>
+        <body>
+        <script type="text/javascript">
+        <!--
+        var pages = $"[%s]" % ", ".join(['"%s"' % v for v in pages])$;
+        var dottedName = get_anchor();
+        if (dottedName) {
+            var target = redirect_url(dottedName);
+            if (target) window.location.replace(target);
+        }
+        // -->
+        </script>
+
+        <h3>Epydoc Auto-redirect page</h3>
+        
+        <p>When javascript is enabled, this page will redirect URLs of
+        the form <tt>redirect.html#<i>dotted.name</i></tt> to the
+        documentation for the object with the given fully-qualified
+        dotted name.</p>
+        <p><a id="message"> &nbsp; </a></p>
+        
+        <script type="text/javascript">
+        <!--
+        if (dottedName) {
+            var msg = document.getElementById("message");
+            msg.innerHTML = "No documentation found for <tt>"+
+                            dottedName+"</tt>";
+        }
+        // -->
+        </script>
+
+        </body>
+        </html>
+        ''')
+        # \------------------------------------------------------------/
+
+    #////////////////////////////////////////////////////////////
+    #{ URLs list
+    #////////////////////////////////////////////////////////////
+
+    def write_api_list(self, out):
+        """
+        Write a list of mapping name->url for all the documented objects.
+        """
+        # Construct a list of all the module & class pages that we're
+        # documenting.  The redirect_url javascript will scan through
+        # this list, looking for a page name that matches the
+        # requested dotted name.
+        skip = (ModuleDoc, ClassDoc, type(UNKNOWN))
+        for val_doc in self.module_list:
+            self.write_url_record(out, val_doc)
+            for var in val_doc.variables.itervalues():
+                if not isinstance(var.value, skip):
+                    self.write_url_record(out, var)
+
+        for val_doc in self.class_list:
+            self.write_url_record(out, val_doc)
+            for var in val_doc.variables.itervalues():
+                self.write_url_record(out, var)
+
+    def write_url_record(self, out, obj):
+        url = self.url(obj)
+        if url is not None:
+            out("%s\t%s\n" % (obj.canonical_name, url))
+
+    #////////////////////////////////////////////////////////////
+    #{ Helper functions
+    #////////////////////////////////////////////////////////////
+
+    def _val_is_public(self, valdoc):
+        """Make a best-guess as to whether the given class is public."""
+        container = self.docindex.container(valdoc)
+        if isinstance(container, NamespaceDoc):
+            for vardoc in container.variables.values():
+                if vardoc in (UNKNOWN, None): continue
+                if vardoc.value is valdoc:
+                    return vardoc.is_public
+        return True
+
+    # [XX] Is it worth-while to pull the anchor tricks that I do here?
+    # Or should I just live with the fact that show/hide private moves
+    # stuff around?
+    write_table_header = compile_template(
+        '''
+        write_table_header(self, out, css_class, heading=None, \
+                           private_link=True, colspan=2)
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        >>> if heading is not None:
+        >>>     anchor = "section-%s" % re.sub("\W", "", heading)
+        <!-- ==================== $heading.upper()$ ==================== -->
+        <a name="$anchor$"></a>
+        >>> #endif
+        <table class="$css_class$" border="1" cellpadding="3"
+               cellspacing="0" width="100%" bgcolor="white">
+        >>> if heading is not None:
+        <tr bgcolor="#70b0f0" class="table-header">
+        >>>     if private_link and self._show_private:
+          <td colspan="$colspan$" class="table-header">
+            <table border="0" cellpadding="0" cellspacing="0" width="100%">
+              <tr valign="top">
+                <td align="left"><span class="table-header">$heading$</span></td>
+                <td align="right" valign="top"
+                 ><span class="options">[<a href="#$anchor$"
+                 class="privatelink" onclick="toggle_private();"
+                 >hide private</a>]</span></td>
+              </tr>
+            </table>
+          </td>
+        >>>     else:
+          <td align="left" colspan="2" class="table-header">
+            <span class="table-header">$heading$</span></td>
+        >>>     #endif
+        </tr>
+        >>> #endif
+        ''')
+        # \------------------------------------------------------------/
+
+    TABLE_FOOTER = '</table>\n'
+
+    PRIVATE_LINK = '''
+    <span class="options">[<a href="javascript:void(0);" class="privatelink"
+    onclick="toggle_private();">hide&nbsp;private</a>]</span>
+    '''.strip()
+
+    write_group_header = compile_template(
+        '''
+        write_group_header(self, out, group, tr_class='')
+        ''',
+        # /------------------------- Template -------------------------\
+        '''
+        <tr bgcolor="#e8f0f8" $tr_class$>
+          <th colspan="2" class="group-header"
+            >&nbsp;&nbsp;&nbsp;&nbsp;$group$</th></tr>
+        ''')
+        # \------------------------------------------------------------/
+
+    _url_cache = {}
+    def url(self, obj):
+        """
+        Return the URL for the given object, which can be a
+        C{VariableDoc}, a C{ValueDoc}, or a C{DottedName}.
+        """
+        cached_url = self._url_cache.get(id(obj))
+        if cached_url is not None:
+            return cached_url
+        else:
+            url = self._url_cache[id(obj)] = self._url(obj)
+            return url
+
+    def _url(self, obj):
+        """
+        Internal helper for L{url}.
+        """
+        # Module: <canonical_name>-module.html
+        if isinstance(obj, ModuleDoc):
+            if obj not in self.module_set: return None
+            return urllib.quote('%s'%obj.canonical_name) + '-module.html'
+        # Class: <canonical_name>-class.html
+        elif isinstance(obj, ClassDoc):
+            if obj not in self.class_set: return None
+            return urllib.quote('%s'%obj.canonical_name) + '-class.html'
+        # Variable
+        elif isinstance(obj, VariableDoc):
+            val_doc = obj.value
+            if isinstance(val_doc, (ModuleDoc, ClassDoc)):
+                return self.url(val_doc)
+            elif obj.container in (None, UNKNOWN):
+                if val_doc in (None, UNKNOWN): return None
+                return self.url(val_doc)
+            elif obj.is_imported == True:
+                if obj.imported_from is not UNKNOWN:
+                    return self.url(obj.imported_from)
+                else:
+                    return None
+            else:
+                container_url = self.url(obj.container)
+                if container_url is None: return None
+                return '%s#%s' % (container_url, urllib.quote('%s'%obj.name))
+        # Value (other than module or class)
+        elif isinstance(obj, ValueDoc):
+            container = self.docindex.container(obj)
+            if container is None:
+                return None # We couldn't find it!
+            else:
+                container_url = self.url(container)
+                if container_url is None: return None
+                anchor = urllib.quote('%s'%obj.canonical_name[-1])
+                return '%s#%s' % (container_url, anchor)
+        # Dotted name: look up the corresponding APIDoc
+        elif isinstance(obj, DottedName):
+            val_doc = self.docindex.get_valdoc(obj)
+            if val_doc is None: return None
+            return self.url(val_doc)
+        # Special pages:
+        elif obj == 'indices':
+            return 'identifier-index.html'
+        elif obj == 'help':
+            return 'help.html'
+        elif obj == 'trees':
+            return self._trees_url
+        else:
+            raise ValueError, "Don't know what to do with %r" % obj
+
+    def pysrc_link(self, api_doc):
+        if not self._incl_sourcecode:
+            return ''
+        url = self.pysrc_url(api_doc)
+        if url is not None: 
+            return ('<span class="codelink"><a href="%s">source&nbsp;'
+                    'code</a></span>' % url)
+        else:
+            return ''
+    
+    def pysrc_url(self, api_doc):
+        if isinstance(api_doc, VariableDoc):
+            if api_doc.value not in (None, UNKNOWN):
+                return pysrc_url(api_doc.value)
+            else:
+                return None
+        elif isinstance(api_doc, ModuleDoc):
+            if api_doc in self.modules_with_sourcecode:
+                return ('%s-pysrc.html' %
+                       urllib.quote('%s' % api_doc.canonical_name))
+            else:
+                return None
+        else:
+            module = api_doc.defining_module
+            if module == UNKNOWN: return None
+            module_pysrc_url = self.pysrc_url(module)
+            if module_pysrc_url is None: return None
+            module_name = module.canonical_name
+            if not module_name.dominates(api_doc.canonical_name, True):
+                log.debug('%r is in %r but name does not dominate' %
+                          (api_doc, module))
+                return module_pysrc_url
+            mname_len = len(module.canonical_name)
+            anchor = '%s' % api_doc.canonical_name[mname_len:]
+            return '%s#%s' % (module_pysrc_url, urllib.quote(anchor))
+        
+        # We didn't find it:
+        return None
+
+    # [xx] add code to automatically do <code> wrapping or the like?
+    def href(self, target, label=None, css_class=None, context=None,
+             tooltip=None):
+        """
+        Return the HTML code for an HREF link to the given target
+        (which can be a C{VariableDoc}, a C{ValueDoc}, or a
+        C{DottedName}.
+        If a C{NamespaceDoc} C{context} is specified, the target label is
+        contextualized to it.
+        """
+        assert isinstance(target, (APIDoc, DottedName))
+
+        # Pick a label, if none was given.
+        if label is None:
+            if isinstance(target, VariableDoc):
+                label = target.name
+            elif (isinstance(target, ValueDoc) and
+                  target.canonical_name is not UNKNOWN):
+                label = target.canonical_name
+            elif isinstance(target, DottedName):
+                label = target
+            elif isinstance(target, GenericValueDoc):
+                raise ValueError("href() should not be called with "
+                                 "GenericValueDoc objects (perhaps you "
+                                 "meant to use the containing variable?)")
+            else:
+                raise ValueError("Unable to find a label for %r" % target)
+                
+            if context is not None and isinstance(label, DottedName):
+                label = label.contextualize(context.canonical_name.container())
+                
+            label = plaintext_to_html(str(label))
+            
+            # Munge names for scripts & unreachable values
+            if label.startswith('script-'):
+                label = label[7:] + ' (script)'
+            if label.startswith('??'):
+                label = '<i>unreachable</i>' + label[2:]
+                label = re.sub(r'-\d+$', '', label)
+
+        # Get the url for the target.
+        url = self.url(target)
+        if url is None:
+            if tooltip: return '<span title="%s">%s</span>' % (tooltip, label)
+            else: return label
+
+        # Construct a string for the class attribute.
+        if css_class is None:
+            css = ''
+        else:
+            css = ' class="%s"' % css_class
+
+        onclick = ''
+        if ((isinstance(target, VariableDoc) and not target.is_public) or
+            (isinstance(target, ValueDoc) and
+             not isinstance(target, GenericValueDoc) and
+             not self._val_is_public(target))):
+            onclick = ' onclick="show_private();"'
+
+        if tooltip:
+            tooltip = ' title="%s"' % tooltip
+        else:
+            tooltip = ''
+
+        return '<a href="%s"%s%s%s>%s</a>' % (url, css, onclick, tooltip, label)
+
+    def _attr_to_html(self, attr, api_doc, indent):
+        if api_doc in (None, UNKNOWN):
+            return ''
+        pds = getattr(api_doc, attr, None) # pds = ParsedDocstring.
+        if pds not in (None, UNKNOWN):
+            return self.docstring_to_html(pds, api_doc, indent)
+        elif isinstance(api_doc, VariableDoc):
+            return self._attr_to_html(attr, api_doc.value, indent)
+        
+    def summary(self, api_doc, indent=0):
+        return self._attr_to_html('summary', api_doc, indent)
+        
+    def descr(self, api_doc, indent=0):
+        return self._attr_to_html('descr', api_doc, indent)
+
+    def type_descr(self, api_doc, indent=0):
+        return self._attr_to_html('type_descr', api_doc, indent)
+
+    def return_type(self, api_doc, indent=0):
+        return self._attr_to_html('return_type', api_doc, indent)
+
+    def return_descr(self, api_doc, indent=0):
+        return self._attr_to_html('return_descr', api_doc, indent)
+
+    def docstring_to_html(self, parsed_docstring, where=None, indent=0):
+        if parsed_docstring in (None, UNKNOWN): return ''
+        linker = _HTMLDocstringLinker(self, where)
+        s = parsed_docstring.to_html(linker, indent=indent,
+                                     directory=self._directory,
+                                     docindex=self.docindex,
+                                     context=where).strip()
+        if self._mark_docstrings:
+            s = '<span class="docstring">%s</span><!--end docstring-->' % s
+        return s
+
+    def description(self, parsed_docstring, where=None, indent=0):
+        assert isinstance(where, (APIDoc, type(None)))
+        if parsed_docstring in (None, UNKNOWN): return ''
+        linker = _HTMLDocstringLinker(self, where)
+        descr = parsed_docstring.to_html(linker, indent=indent,
+                                         directory=self._directory,
+                                         docindex=self.docindex,
+                                         context=where).strip()
+        if descr == '': return '&nbsp;'
+        return descr
+
+    # [xx] Should this be defined by the APIDoc classes themselves??
+    def doc_kind(self, doc):
+        if isinstance(doc, ModuleDoc) and doc.is_package == True:
+            return 'Package'
+        elif (isinstance(doc, ModuleDoc) and
+              doc.canonical_name[0].startswith('script')):
+            return 'Script'
+        elif isinstance(doc, ModuleDoc):
+            return 'Module'
+        elif isinstance(doc, ClassDoc):
+            return 'Class'
+        elif isinstance(doc, ClassMethodDoc):
+            return 'Class Method'
+        elif isinstance(doc, StaticMethodDoc):
+            return 'Static Method'
+        elif isinstance(doc, RoutineDoc):
+            if isinstance(self.docindex.container(doc), ClassDoc):
+                return 'Method'
+            else:
+                return 'Function'
+        else:
+            return 'Variable'
+        
+    def _doc_or_ancestor_is_private(self, api_doc):
+        name = api_doc.canonical_name
+        for i in range(len(name), 0, -1):
+            # Is it (or an ancestor) a private var?
+            var_doc = self.docindex.get_vardoc(name[:i])
+            if var_doc is not None and var_doc.is_public == False:
+                return True
+            # Is it (or an ancestor) a private module?
+            val_doc = self.docindex.get_valdoc(name[:i])
+            if (val_doc is not None and isinstance(val_doc, ModuleDoc) and
+                val_doc.canonical_name[-1].startswith('_')):
+                return True
+        return False
+
+    def _private_subclasses(self, class_doc):
+        """Return a list of all subclasses of the given class that are
+        private, as determined by L{_val_is_private}.  Recursive
+        subclasses are included in this list."""
+        queue = [class_doc]
+        private = set()
+        for cls in queue:
+            if (isinstance(cls, ClassDoc) and
+                cls.subclasses not in (None, UNKNOWN)):
+                queue.extend(cls.subclasses)
+                private.update([c for c in cls.subclasses if
+                                not self._val_is_public(c)])
+        return private
+                
+class _HTMLDocstringLinker(epydoc.markup.DocstringLinker):
+    def __init__(self, htmlwriter, container):
+        self.htmlwriter = htmlwriter
+        self.docindex = htmlwriter.docindex
+        self.container = container
+        
+    def translate_indexterm(self, indexterm):
+        key = self.htmlwriter._term_index_to_anchor(indexterm)
+        return ('<a name="%s"></a><i class="indexterm">%s</i>' %
+                (key, indexterm.to_html(self)))
+    
+    def translate_identifier_xref(self, identifier, label=None):
+        # Pick a label for this xref.
+        if label is None: label = plaintext_to_html(identifier)
+
+        # Find the APIDoc for it (if it's available).
+        doc = self.docindex.find(identifier, self.container)
+
+        # If we didn't find a target, then try checking in the contexts
+        # of the ancestor classes. 
+        if doc is None and isinstance(self.container, RoutineDoc):
+            container = self.docindex.get_vardoc(
+                self.container.canonical_name)
+            while (doc is None and container not in (None, UNKNOWN)
+                   and container.overrides not in (None, UNKNOWN)):
+                container = container.overrides
+                doc = self.docindex.find(identifier, container)
+                
+        # Translate it into HTML.
+        if doc is None:
+            self._failed_xref(identifier)
+            return '<code class="link">%s</code>' % label
+        else:
+            return self.htmlwriter.href(doc, label, 'link')
+
+    # [xx] Should this be added to the DocstringLinker interface???
+    # Currently, this is *only* used by dotgraph.
+    def url_for(self, identifier):
+        if isinstance(identifier, (basestring, DottedName)):
+            doc = self.docindex.find(identifier, self.container)
+            if doc:
+                return self.htmlwriter.url(doc)
+            else:
+                return None
+            
+        elif isinstance(identifier, APIDoc):
+            return self.htmlwriter.url(identifier)
+            doc = identifier
+            
+        else:
+            raise TypeError('Expected string or APIDoc')
+
+    def _failed_xref(self, identifier):
+        """Add an identifier to the htmlwriter's failed crossreference
+        list."""
+        # Don't count it as a failed xref if it's a parameter of the
+        # current function.
+        if (isinstance(self.container, RoutineDoc) and
+            identifier in self.container.all_args()):
+            return
+        
+        failed_xrefs = self.htmlwriter._failed_xrefs
+        context = self.container.canonical_name
+        failed_xrefs.setdefault(identifier,{})[context] = 1