#
# rst.py: ReStructuredText docstring parsing
# Edward Loper
#
# Created [06/28/03 02:52 AM]
# $Id: restructuredtext.py 1661 2007-11-07 12:59:34Z dvarrazzo $
#

"""
Epydoc parser for ReStructuredText strings.  ReStructuredText is the
standard markup language used by the Docutils project.
L{parse_docstring()} provides the primary interface to this module; it
returns a L{ParsedRstDocstring}, which supports all of the methods
defined by L{ParsedDocstring}.

L{ParsedRstDocstring} is basically just a L{ParsedDocstring} wrapper
for the C{docutils.nodes.document} class.

Creating C{ParsedRstDocstring}s
===============================

C{ParsedRstDocstring}s are created by the C{parse_document} function,
using the C{docutils.core.publish_string()} method, with the following
helpers:

  - An L{_EpydocReader} is used to capture all error messages as it
    parses the docstring.
  - A L{_DocumentPseudoWriter} is used to extract the document itself,
    without actually writing any output.  The document is saved for
    further processing.  The settings for the writer are copied from
    C{docutils.writers.html4css1.Writer}, since those settings will
    be used when we actually write the docstring to html.

Using C{ParsedRstDocstring}s
============================

C{ParsedRstDocstring}s support all of the methods defined by
C{ParsedDocstring}; but only the following four methods have
non-default behavior:

  - L{to_html()<ParsedRstDocstring.to_html>} uses an
    L{_EpydocHTMLTranslator} to translate the C{ParsedRstDocstring}'s
    document into an HTML segment.
  - L{split_fields()<ParsedRstDocstring.split_fields>} uses a
    L{_SplitFieldsTranslator} to divide the C{ParsedRstDocstring}'s
    document into its main body and its fields.  Special handling
    is done to account for consolidated fields.
  - L{summary()<ParsedRstDocstring.summary>} uses a
    L{_SummaryExtractor} to extract the first sentence from
    the C{ParsedRstDocstring}'s document.
  - L{to_plaintext()<ParsedRstDocstring.to_plaintext>} uses
    C{document.astext()} to convert the C{ParsedRstDocstring}'s
    document to plaintext.

@todo: Add ParsedRstDocstring.to_latex()
@var CONSOLIDATED_FIELDS: A dictionary encoding the set of
'consolidated fields' that can be used.  Each consolidated field is
marked by a single tag, and contains a single bulleted list, where
each list item starts with an identifier, marked as interpreted text
(C{`...`}).  This module automatically splits these consolidated
fields into individual fields.  The keys of C{CONSOLIDATED_FIELDS} are
the names of possible consolidated fields; and the values are the
names of the field tags that should be used for individual entries in
the list.
"""
__docformat__ = 'epytext en'

# Imports
import re, os, os.path
from xml.dom.minidom import *

from docutils.core import publish_string
from docutils.writers import Writer
from docutils.writers.html4css1 import HTMLTranslator, Writer as HTMLWriter
from docutils.writers.latex2e import LaTeXTranslator, Writer as LaTeXWriter
from docutils.readers.standalone import Reader as StandaloneReader
from docutils.utils import new_document
from docutils.nodes import NodeVisitor, Text, SkipChildren
from docutils.nodes import SkipNode, TreeCopyVisitor
from docutils.frontend import OptionParser
from docutils.parsers.rst import directives, roles
import docutils.nodes
import docutils.transforms.frontmatter
import docutils.transforms
import docutils.utils

from epydoc.compat import * # Backwards compatibility
from epydoc.markup import *
from epydoc.apidoc import ModuleDoc, ClassDoc
from epydoc.docwriter.dotgraph import *
from epydoc.docwriter.xlink import ApiLinkReader
from epydoc.markup.doctest import doctest_to_html, doctest_to_latex, \
                                  HTMLDoctestColorizer

#: A dictionary whose keys are the "consolidated fields" that are
#: recognized by epydoc; and whose values are the corresponding epydoc
#: field names that should be used for the individual fields.
CONSOLIDATED_FIELDS = {
    'parameters': 'param',
    'arguments': 'arg',
    'exceptions': 'except',
    'variables': 'var',
    'ivariables': 'ivar',
    'cvariables': 'cvar',
    'groups': 'group',
    'types': 'type',
    'keywords': 'keyword',
    }

#: A list of consolidated fields whose bodies may be specified using a
#: definition list, rather than a bulleted list.  For these fields, the
#: 'classifier' for each term in the definition list is translated into
#: a @type field.
CONSOLIDATED_DEFLIST_FIELDS = ['param', 'arg', 'var', 'ivar', 'cvar', 'keyword']

def parse_docstring(docstring, errors, **options):
    """
    Parse the given docstring, which is formatted using
    ReStructuredText; and return a L{ParsedDocstring} representation
    of its contents.
    @param docstring: The docstring to parse
    @type docstring: C{string}
    @param errors: A list where any errors generated during parsing
        will be stored.
    @type errors: C{list} of L{ParseError}
    @param options: Extra options.  Unknown options are ignored.
        Currently, no extra options are defined.
    @rtype: L{ParsedDocstring}
    """
    writer = _DocumentPseudoWriter()
    reader = _EpydocReader(errors) # Outputs errors to the list.
    publish_string(docstring, writer=writer, reader=reader,
                   settings_overrides={'report_level':10000,
                                       'halt_level':10000,
                                       'warning_stream':None})
    return ParsedRstDocstring(writer.document)

class OptimizedReporter(docutils.utils.Reporter):
    """A reporter that ignores all debug messages.  This is used to
    shave a couple seconds off of epydoc's run time, since docutils
    isn't very fast about processing its own debug messages."""
    def debug(self, *args, **kwargs): pass

class ParsedRstDocstring(ParsedDocstring):
    """
    An encoded version of a ReStructuredText docstring.  The contents
    of the docstring are encoded in the L{_document} instance
    variable.

    @ivar _document: A ReStructuredText document, encoding the
        docstring.
    @type _document: C{docutils.nodes.document}
    """
    def __init__(self, document):
        """
        @type document: C{docutils.nodes.document}
        """
        self._document = document
        
        # The default document reporter and transformer are not
        # pickle-able; so replace them with stubs that are.
        document.reporter = OptimizedReporter(
            document.reporter.source, 'SEVERE', 'SEVERE', '')
        document.transformer = docutils.transforms.Transformer(document)

    def split_fields(self, errors=None):
        # Inherit docs
        if errors is None: errors = []
        visitor = _SplitFieldsTranslator(self._document, errors)
        self._document.walk(visitor)
        if len(self._document.children) > 0:
            return self, visitor.fields
        else:
            return None, visitor.fields

    def summary(self):
        # Inherit docs
        visitor = _SummaryExtractor(self._document)
        try: self._document.walk(visitor)
        except docutils.nodes.NodeFound: pass
        return visitor.summary, bool(visitor.other_docs)

#     def concatenate(self, other):
#         result = self._document.copy()
#         for child in (self._document.get_children() +
#                       other._document.get_children()):
#             visitor = TreeCopyVisitor(self._document)
#             child.walkabout(visitor)
#             result.append(visitor.get_tree_copy())
#         return ParsedRstDocstring(result)
        
    def to_html(self, docstring_linker, directory=None,
                docindex=None, context=None, **options):
        # Inherit docs
        visitor = _EpydocHTMLTranslator(self._document, docstring_linker,
                                        directory, docindex, context)
        self._document.walkabout(visitor)
        return ''.join(visitor.body)

    def to_latex(self, docstring_linker, **options):
        # Inherit docs
        visitor = _EpydocLaTeXTranslator(self._document, docstring_linker)
        self._document.walkabout(visitor)
        return ''.join(visitor.body)

    def to_plaintext(self, docstring_linker, **options):
        # This is should be replaced by something better:
        return self._document.astext() 

    def __repr__(self): return '<ParsedRstDocstring: ...>'

    def index_terms(self):
        visitor = _TermsExtractor(self._document)
        self._document.walkabout(visitor)
        return visitor.terms

class _EpydocReader(ApiLinkReader):
    """
    A reader that captures all errors that are generated by parsing,
    and appends them to a list.
    """
    # Remove the DocInfo transform, to ensure that :author: fields are
    # correctly handled.  This needs to be handled differently
    # depending on the version of docutils that's being used, because
    # the default_transforms attribute was deprecated & replaced by
    # get_transforms().
    version = [int(v) for v in docutils.__version__.split('.')]
    version += [ 0 ] * (3 - len(version))
    if version < [0,4,0]:
        default_transforms = list(ApiLinkReader.default_transforms)
        try: default_transforms.remove(docutils.transforms.frontmatter.DocInfo)
        except ValueError: pass
    else:
        def get_transforms(self):
            return [t for t in ApiLinkReader.get_transforms(self)
                    if t != docutils.transforms.frontmatter.DocInfo]
    del version

    def __init__(self, errors):
        self._errors = errors
        ApiLinkReader.__init__(self)
        
    def new_document(self):
        document = new_document(self.source.source_path, self.settings)
        # Capture all warning messages.
        document.reporter.attach_observer(self.report)
        # These are used so we know how to encode warning messages:
        self._encoding = document.reporter.encoding
        self._error_handler = document.reporter.error_handler
        # Return the new document.
        return document

    def report(self, error):
        try: is_fatal = int(error['level']) > 2
        except: is_fatal = 1
        try: linenum = int(error['line'])
        except: linenum = None

        msg = ''.join([c.astext().encode(self._encoding, self._error_handler)
                       for c in error])

        self._errors.append(ParseError(msg, linenum, is_fatal))
        
class _DocumentPseudoWriter(Writer):
    """
    A pseudo-writer for the docutils framework, that can be used to
    access the document itself.  The output of C{_DocumentPseudoWriter}
    is just an empty string; but after it has been used, the most
    recently processed document is available as the instance variable
    C{document}

    @type document: C{docutils.nodes.document}
    @ivar document: The most recently processed document.
    """
    def __init__(self):
        self.document = None
        Writer.__init__(self)
        
    def translate(self):
        self.output = ''
        
class _SummaryExtractor(NodeVisitor):
    """
    A docutils node visitor that extracts the first sentence from
    the first paragraph in a document.
    """
    def __init__(self, document):
        NodeVisitor.__init__(self, document)
        self.summary = None
        self.other_docs = None
        
    def visit_document(self, node):
        self.summary = None
        
    _SUMMARY_RE = re.compile(r'(\s*[\w\W]*?\.)(\s|$)')
    def visit_paragraph(self, node):
        if self.summary is not None:
            # found a paragraph after the first one
            self.other_docs = True
            raise docutils.nodes.NodeFound('Found summary')

        summary_pieces = []

        # Extract the first sentence.
        for child in node:
            if isinstance(child, docutils.nodes.Text):
                m = self._SUMMARY_RE.match(child.data)
                if m:
                    summary_pieces.append(docutils.nodes.Text(m.group(1)))
                    other = child.data[m.end():]
                    if other and not other.isspace():
                        self.other_docs = True
                    break
            summary_pieces.append(child)

        summary_doc = self.document.copy() # shallow copy
        summary_para = node.copy() # shallow copy
        summary_doc[:] = [summary_para]
        summary_para[:] = summary_pieces
        self.summary = ParsedRstDocstring(summary_doc)

    def visit_field(self, node):
        raise SkipNode

    def unknown_visit(self, node):
        'Ignore all unknown nodes'

class _TermsExtractor(NodeVisitor):
    """
    A docutils node visitor that extracts the terms from documentation.

    Terms are created using the C{:term:} interpreted text role.
    """
    def __init__(self, document):
        NodeVisitor.__init__(self, document)
        
        self.terms = None
        """
        The terms currently found.
        @type: C{list}
        """
        
    def visit_document(self, node):
        self.terms = []
        self._in_term = False

    def visit_emphasis(self, node):
        if 'term' in node.get('classes'):
            self._in_term = True

    def depart_emphasis(self, node):
        if 'term' in node.get('classes'):
            self._in_term = False

    def visit_Text(self, node):
        if self._in_term:
            doc = self.document.copy()
            doc[:] = [node.copy()]
            self.terms.append(ParsedRstDocstring(doc))

    def unknown_visit(self, node):
        'Ignore all unknown nodes'

    def unknown_departure(self, node):
        'Ignore all unknown nodes'

class _SplitFieldsTranslator(NodeVisitor):
    """
    A docutils translator that removes all fields from a document, and
    collects them into the instance variable C{fields}

    @ivar fields: The fields of the most recently walked document.
    @type fields: C{list} of L{Field<markup.Field>}
    """
    
    ALLOW_UNMARKED_ARG_IN_CONSOLIDATED_FIELD = True
    """If true, then consolidated fields are not required to mark
    arguments with C{`backticks`}.  (This is currently only
    implemented for consolidated fields expressed as definition lists;
    consolidated fields expressed as unordered lists still require
    backticks for now."""
    
    def __init__(self, document, errors):
        NodeVisitor.__init__(self, document)
        self._errors = errors
        self.fields = []
        self._newfields = {}

    def visit_document(self, node):
        self.fields = []

    def visit_field(self, node):
        # Remove the field from the tree.
        node.parent.remove(node)

        # Extract the field name & optional argument
        tag = node[0].astext().split(None, 1)
        tagname = tag[0]
        if len(tag)>1: arg = tag[1]
        else: arg = None

        # Handle special fields:
        fbody = node[1]
        if arg is None:
            for (list_tag, entry_tag) in CONSOLIDATED_FIELDS.items():
                if tagname.lower() == list_tag:
                    try:
                        self.handle_consolidated_field(fbody, entry_tag)
                        return
                    except ValueError, e:
                        estr = 'Unable to split consolidated field '
                        estr += '"%s" - %s' % (tagname, e)
                        self._errors.append(ParseError(estr, node.line,
                                                       is_fatal=0))
                        
                        # Use a @newfield to let it be displayed as-is.
                        if tagname.lower() not in self._newfields:
                            newfield = Field('newfield', tagname.lower(),
                                             parse(tagname, 'plaintext'))
                            self.fields.append(newfield)
                            self._newfields[tagname.lower()] = 1
                        
        self._add_field(tagname, arg, fbody)

    def _add_field(self, tagname, arg, fbody):
        field_doc = self.document.copy()
        for child in fbody: field_doc.append(child)
        field_pdoc = ParsedRstDocstring(field_doc)
        self.fields.append(Field(tagname, arg, field_pdoc))
            
    def visit_field_list(self, node):
        # Remove the field list from the tree.  The visitor will still walk
        # over the node's children.
        node.parent.remove(node)

    def handle_consolidated_field(self, body, tagname):
        """
        Attempt to handle a consolidated section.
        """
        if len(body) != 1:
            raise ValueError('does not contain a single list.')
        elif body[0].tagname == 'bullet_list':
            self.handle_consolidated_bullet_list(body[0], tagname)
        elif (body[0].tagname == 'definition_list' and
              tagname in CONSOLIDATED_DEFLIST_FIELDS):
            self.handle_consolidated_definition_list(body[0], tagname)
        elif tagname in CONSOLIDATED_DEFLIST_FIELDS:
            raise ValueError('does not contain a bulleted list or '
                             'definition list.')
        else:
            raise ValueError('does not contain a bulleted list.')

    def handle_consolidated_bullet_list(self, items, tagname):
        # Check the contents of the list.  In particular, each list
        # item should have the form:
        #   - `arg`: description...
        n = 0
        _BAD_ITEM = ("list item %d is not well formed.  Each item must "
                     "consist of a single marked identifier (e.g., `x`), "
                     "optionally followed by a colon or dash and a "
                     "description.")
        for item in items:
            n += 1
            if item.tagname != 'list_item' or len(item) == 0: 
                raise ValueError('bad bulleted list (bad child %d).' % n)
            if item[0].tagname != 'paragraph':
                if item[0].tagname == 'definition_list':
                    raise ValueError(('list item %d contains a definition '+
                                      'list (it\'s probably indented '+
                                      'wrong).') % n)
                else:
                    raise ValueError(_BAD_ITEM % n)
            if len(item[0]) == 0: 
                raise ValueError(_BAD_ITEM % n)
            if item[0][0].tagname != 'title_reference':
                raise ValueError(_BAD_ITEM % n)

        # Everything looks good; convert to multiple fields.
        for item in items:
            # Extract the arg
            arg = item[0][0].astext()

            # Extract the field body, and remove the arg
            fbody = item[:]
            fbody[0] = fbody[0].copy()
            fbody[0][:] = item[0][1:]

            # Remove the separating ":", if present
            if (len(fbody[0]) > 0 and
                isinstance(fbody[0][0], docutils.nodes.Text)):
                child = fbody[0][0]
                if child.data[:1] in ':-':
                    child.data = child.data[1:].lstrip()
                elif child.data[:2] in (' -', ' :'):
                    child.data = child.data[2:].lstrip()

            # Wrap the field body, and add a new field
            self._add_field(tagname, arg, fbody)
        
    def handle_consolidated_definition_list(self, items, tagname):
        # Check the list contents.
        n = 0
        _BAD_ITEM = ("item %d is not well formed.  Each item's term must "
                     "consist of a single marked identifier (e.g., `x`), "
                     "optionally followed by a space, colon, space, and "
                     "a type description.")
        for item in items:
            n += 1
            if (item.tagname != 'definition_list_item' or len(item) < 2 or
                item[0].tagname != 'term' or
                item[-1].tagname != 'definition'):
                raise ValueError('bad definition list (bad child %d).' % n)
            if len(item) > 3:
                raise ValueError(_BAD_ITEM % n)
            if not ((item[0][0].tagname == 'title_reference') or
                    (self.ALLOW_UNMARKED_ARG_IN_CONSOLIDATED_FIELD and
                     isinstance(item[0][0], docutils.nodes.Text))):
                raise ValueError(_BAD_ITEM % n)
            for child in item[0][1:]:
                if child.astext() != '':
                    raise ValueError(_BAD_ITEM % n)

        # Extract it.
        for item in items:
            # The basic field.
            arg = item[0][0].astext()
            fbody = item[-1]
            self._add_field(tagname, arg, fbody)
            # If there's a classifier, treat it as a type.
            if len(item) == 3:
                type_descr = item[1]
                self._add_field('type', arg, type_descr)

    def unknown_visit(self, node):
        'Ignore all unknown nodes'

def latex_head_prefix():
    document = new_document('<fake>')
    translator = _EpydocLaTeXTranslator(document, None)
    return translator.head_prefix
    
class _EpydocLaTeXTranslator(LaTeXTranslator):
    settings = None
    def __init__(self, document, docstring_linker):
        # Set the document's settings.
        if self.settings is None:
            settings = OptionParser([LaTeXWriter()]).get_default_values()
            settings.output_encoding = 'utf-8'
            self.__class__.settings = settings
        document.settings = self.settings

        LaTeXTranslator.__init__(self, document)
        self._linker = docstring_linker

        # Start at section level 3.  (Unfortunately, we now have to
        # set a private variable to make this work; perhaps the standard
        # latex translator should grow an official way to spell this?)
        self.section_level = 3
        self._section_number = [0]*self.section_level

    # Handle interpreted text (crossreferences)
    def visit_title_reference(self, node):
        target = self.encode(node.astext())
        xref = self._linker.translate_identifier_xref(target, target)
        self.body.append(xref)
        raise SkipNode()

    def visit_document(self, node): pass
    def depart_document(self, node): pass

    # For now, just ignore dotgraphs. [XXX]
    def visit_dotgraph(self, node):
        log.warning("Ignoring dotgraph in latex output (dotgraph "
                    "rendering for latex not implemented yet).")
        raise SkipNode()
    
    def visit_doctest_block(self, node):
        self.body.append(doctest_to_latex(node[0].astext()))
        raise SkipNode()

class _EpydocHTMLTranslator(HTMLTranslator):
    settings = None
    def __init__(self, document, docstring_linker, directory,
                 docindex, context):
        self._linker = docstring_linker
        self._directory = directory
        self._docindex = docindex
        self._context = context
        
        # Set the document's settings.
        if self.settings is None:
            settings = OptionParser([HTMLWriter()]).get_default_values()
            self.__class__.settings = settings
        document.settings = self.settings

        # Call the parent constructor.
        HTMLTranslator.__init__(self, document)

    # Handle interpreted text (crossreferences)
    def visit_title_reference(self, node):
        target = self.encode(node.astext())
        xref = self._linker.translate_identifier_xref(target, target)
        self.body.append(xref)
        raise SkipNode()

    def should_be_compact_paragraph(self, node):
        if self.document.children == [node]:
            return True
        else:
            return HTMLTranslator.should_be_compact_paragraph(self, node)

    def visit_document(self, node): pass
    def depart_document(self, node): pass
        
    def starttag(self, node, tagname, suffix='\n', **attributes):
        """
        This modified version of starttag makes a few changes to HTML
        tags, to prevent them from conflicting with epydoc.  In particular:
          - existing class attributes are prefixed with C{'rst-'}
          - existing names are prefixed with C{'rst-'}
          - hrefs starting with C{'#'} are prefixed with C{'rst-'}
          - hrefs not starting with C{'#'} are given target='_top'
          - all headings (C{<hM{n}>}) are given the css class C{'heading'}
        """
        # Get the list of all attribute dictionaries we need to munge.
        attr_dicts = [attributes]
        if isinstance(node, docutils.nodes.Node):
            attr_dicts.append(node.attributes)
        if isinstance(node, dict):
            attr_dicts.append(node)
        # Munge each attribute dictionary.  Unfortunately, we need to
        # iterate through attributes one at a time because some
        # versions of docutils don't case-normalize attributes.
        for attr_dict in attr_dicts:
            for (key, val) in attr_dict.items():
                # Prefix all CSS classes with "rst-"; and prefix all
                # names with "rst-" to avoid conflicts.
                if key.lower() in ('class', 'id', 'name'):
                    attr_dict[key] = 'rst-%s' % val
                elif key.lower() in ('classes', 'ids', 'names'):
                    attr_dict[key] = ['rst-%s' % cls for cls in val]
                elif key.lower() == 'href':
                    if attr_dict[key][:1]=='#':
                        attr_dict[key] = '#rst-%s' % attr_dict[key][1:]
                    else:
                        # If it's an external link, open it in a new
                        # page.
                        attr_dict['target'] = '_top'

        # For headings, use class="heading"
        if re.match(r'^h\d+$', tagname):
            attributes['class'] = ' '.join([attributes.get('class',''),
                                            'heading']).strip()
        
        return HTMLTranslator.starttag(self, node, tagname, suffix,
                                       **attributes)

    def visit_dotgraph(self, node):
        if self._directory is None: return # [xx] warning?
        
        # Generate the graph.
        graph = node.graph(self._docindex, self._context, self._linker)
        if graph is None: return
        
        # Write the graph.
        image_url = '%s.gif' % graph.uid
        image_file = os.path.join(self._directory, image_url)
        self.body.append(graph.to_html(image_file, image_url))
        raise SkipNode()

    def visit_doctest_block(self, node):
        pysrc = node[0].astext()
        if node.get('codeblock'):
            self.body.append(HTMLDoctestColorizer().colorize_codeblock(pysrc))
        else:
            self.body.append(doctest_to_html(pysrc))
        raise SkipNode()

    def visit_emphasis(self, node):
        # Generate a corrent index term anchor
        if 'term' in node.get('classes') and node.children:
            doc = self.document.copy()
            doc[:] = [node.children[0].copy()]
            self.body.append(
                self._linker.translate_indexterm(ParsedRstDocstring(doc)))
            raise SkipNode()

        HTMLTranslator.visit_emphasis(self, node)

def python_code_directive(name, arguments, options, content, lineno,
                          content_offset, block_text, state, state_machine):
    """
    A custom restructuredtext directive which can be used to display
    syntax-highlighted Python code blocks.  This directive takes no
    arguments, and the body should contain only Python code.  This
    directive can be used instead of doctest blocks when it is
    inconvenient to list prompts on each line, or when you would
    prefer that the output not contain prompts (e.g., to make
    copy/paste easier).
    """
    required_arguments = 0
    optional_arguments = 0

    text = '\n'.join(content)
    node = docutils.nodes.doctest_block(text, text, codeblock=True)
    return [ node ]
    
python_code_directive.arguments = (0, 0, 0)
python_code_directive.content = True

directives.register_directive('python', python_code_directive)

def term_role(name, rawtext, text, lineno, inliner,
            options={}, content=[]):

    text = docutils.utils.unescape(text)
    node = docutils.nodes.emphasis(rawtext, text, **options)
    node.attributes['classes'].append('term')

    return [node], []

roles.register_local_role('term', term_role)

######################################################################
#{ Graph Generation Directives
######################################################################
# See http://docutils.sourceforge.net/docs/howto/rst-directives.html

class dotgraph(docutils.nodes.image):
    """
    A custom docutils node that should be rendered using Graphviz dot.
    This node does not directly store the graph; instead, it stores a
    pointer to a function that can be used to generate the graph.
    This allows the graph to be built based on information that might
    not be available yet at parse time.  This graph generation
    function has the following signature:

        >>> def generate_graph(docindex, context, linker, *args):
        ...     'generates and returns a new DotGraph'

    Where C{docindex} is a docindex containing the documentation that
    epydoc has built; C{context} is the C{APIDoc} whose docstring
    contains this dotgraph node; C{linker} is a L{DocstringLinker}
    that can be used to resolve crossreferences; and C{args} is any
    extra arguments that are passed to the C{dotgraph} constructor.
    """
    def __init__(self, generate_graph_func, *generate_graph_args):
        docutils.nodes.image.__init__(self)
        self.graph_func = generate_graph_func
        self.args = generate_graph_args
    def graph(self, docindex, context, linker):
        return self.graph_func(docindex, context, linker, *self.args)

def _dir_option(argument):
    """A directive option spec for the orientation of a graph."""
    argument = argument.lower().strip()
    if argument == 'right': return 'LR'
    if argument == 'left': return 'RL'
    if argument == 'down': return 'TB'
    if argument == 'up': return 'BT'
    raise ValueError('%r unknown; choose from left, right, up, down' %
                     argument)
 
def digraph_directive(name, arguments, options, content, lineno,
                      content_offset, block_text, state, state_machine):
    """
    A custom restructuredtext directive which can be used to display
    Graphviz dot graphs.  This directive takes a single argument,
    which is used as the graph's name.  The contents of the directive
    are used as the body of the graph.  Any href attributes whose
    value has the form <name> will be replaced by the URL of the object
    with that name.  Here's a simple example::

     .. digraph:: example_digraph
       a -> b -> c
       c -> a [dir=\"none\"]
    """
    if arguments: title = arguments[0]
    else: title = ''
    return [ dotgraph(_construct_digraph, title, options.get('caption'),
                    '\n'.join(content)) ]
digraph_directive.arguments = (0, 1, True)
digraph_directive.options = {'caption': directives.unchanged}
digraph_directive.content = True
directives.register_directive('digraph', digraph_directive)

def _construct_digraph(docindex, context, linker, title, caption,
                       body):
    """Graph generator for L{digraph_directive}"""
    graph = DotGraph(title, body, caption=caption)
    graph.link(linker)
    return graph

def classtree_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state, state_machine):
    """
    A custom restructuredtext directive which can be used to
    graphically display a class hierarchy.  If one or more arguments
    are given, then those classes and all their descendants will be
    displayed.  If no arguments are given, and the directive is in a
    class's docstring, then that class and all its descendants will be
    displayed.  It is an error to use this directive with no arguments
    in a non-class docstring.

    Options:
      - C{:dir:} -- Specifies the orientation of the graph.  One of
        C{down}, C{right} (default), C{left}, C{up}.
    """
    return [ dotgraph(_construct_classtree, arguments, options) ]
classtree_directive.arguments = (0, 1, True)
classtree_directive.options = {'dir': _dir_option}
classtree_directive.content = False
directives.register_directive('classtree', classtree_directive)

def _construct_classtree(docindex, context, linker, arguments, options):
    """Graph generator for L{classtree_directive}"""
    if len(arguments) == 1:
        bases = [docindex.find(name, context) for name in
                 arguments[0].replace(',',' ').split()]
        bases = [d for d in bases if isinstance(d, ClassDoc)]
    elif isinstance(context, ClassDoc):
        bases = [context]
    else:
        log.warning("Could not construct class tree: you must "
                    "specify one or more base classes.")
        return None
        
    return class_tree_graph(bases, linker, context, **options)

def packagetree_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state, state_machine):
    """
    A custom restructuredtext directive which can be used to
    graphically display a package hierarchy.  If one or more arguments
    are given, then those packages and all their submodules will be
    displayed.  If no arguments are given, and the directive is in a
    package's docstring, then that package and all its submodules will
    be displayed.  It is an error to use this directive with no
    arguments in a non-package docstring.

    Options:
      - C{:dir:} -- Specifies the orientation of the graph.  One of
        C{down}, C{right} (default), C{left}, C{up}.
    """
    return [ dotgraph(_construct_packagetree, arguments, options) ]
packagetree_directive.arguments = (0, 1, True)
packagetree_directive.options = {
  'dir': _dir_option,
  'style': lambda a:directives.choice(a.lower(), ('uml', 'tree'))}
packagetree_directive.content = False
directives.register_directive('packagetree', packagetree_directive)

def _construct_packagetree(docindex, context, linker, arguments, options):
    """Graph generator for L{packagetree_directive}"""
    if len(arguments) == 1:
        packages = [docindex.find(name, context) for name in
                    arguments[0].replace(',',' ').split()]
        packages = [d for d in packages if isinstance(d, ModuleDoc)]
    elif isinstance(context, ModuleDoc):
        packages = [context]
    else:
        log.warning("Could not construct package tree: you must "
                    "specify one or more root packages.")
        return None

    return package_tree_graph(packages, linker, context, **options)

def importgraph_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state, state_machine):
    return [ dotgraph(_construct_importgraph, arguments, options) ]
importgraph_directive.arguments = (0, 1, True)
importgraph_directive.options = {'dir': _dir_option}
importgraph_directive.content = False
directives.register_directive('importgraph', importgraph_directive)

def _construct_importgraph(docindex, context, linker, arguments, options):
    """Graph generator for L{importgraph_directive}"""
    if len(arguments) == 1:
        modules = [ docindex.find(name, context)
                    for name in arguments[0].replace(',',' ').split() ]
        modules = [d for d in modules if isinstance(d, ModuleDoc)]
    else:
        modules = [d for d in docindex.root if isinstance(d, ModuleDoc)]

    return import_graph(modules, docindex, linker, context, **options)

def callgraph_directive(name, arguments, options, content, lineno,
                        content_offset, block_text, state, state_machine):
    return [ dotgraph(_construct_callgraph, arguments, options) ]
callgraph_directive.arguments = (0, 1, True)
callgraph_directive.options = {'dir': _dir_option,
                                 'add_callers': directives.flag,
                                 'add_callees': directives.flag}
callgraph_directive.content = False
directives.register_directive('callgraph', callgraph_directive)

def _construct_callgraph(docindex, context, linker, arguments, options):
    """Graph generator for L{callgraph_directive}"""
    if len(arguments) == 1:
        docs = [docindex.find(name, context) for name in
                 arguments[0].replace(',',' ').split()]
        docs = [doc for doc in docs if doc is not None]
    else:
        docs = [context]
    return call_graph(docs, docindex, linker, context, **options)