epydoc.markup.restructuredtext

Package epydoc :: Package markup :: Module restructuredtext |
[hide private]
[frames] | no frames]

# Source Code for Module epydoc.markup.restructuredtext

      1  #
      2  # rst.py: ReStructuredText docstring parsing
      3  # Edward Loper
      4  #
      5  # Created [06/28/03 02:52 AM]
      6  # $Id: restructuredtext.py 1661 2007-11-07 12:59:34Z dvarrazzo $
      7  #
      8
      9  """
     10  Epydoc parser for ReStructuredText strings.  ReStructuredText is the
     11  standard markup language used by the Docutils project.
     12  L{parse_docstring()} provides the primary interface to this module; it
     13  returns a L{ParsedRstDocstring}, which supports all of the methods
     14  defined by L{ParsedDocstring}.
     15
     16  L{ParsedRstDocstring} is basically just a L{ParsedDocstring} wrapper
     17  for the C{docutils.nodes.document} class.
     18
     19  Creating C{ParsedRstDocstring}s
     20  ===============================
     21
     22  C{ParsedRstDocstring}s are created by the C{parse_document} function,
     23  using the C{docutils.core.publish_string()} method, with the following
     24  helpers:
     25
     26    - An L{_EpydocReader} is used to capture all error messages as it
     27      parses the docstring.
     28    - A L{_DocumentPseudoWriter} is used to extract the document itself,
     29      without actually writing any output.  The document is saved for
     30      further processing.  The settings for the writer are copied from
     31      C{docutils.writers.html4css1.Writer}, since those settings will
     32      be used when we actually write the docstring to html.
     33
     34  Using C{ParsedRstDocstring}s
     35  ============================
     36
     37  C{ParsedRstDocstring}s support all of the methods defined by
     38  C{ParsedDocstring}; but only the following four methods have
     39  non-default behavior:
     40
     41    - L{to_html()<ParsedRstDocstring.to_html>} uses an
     42      L{_EpydocHTMLTranslator} to translate the C{ParsedRstDocstring}'s
     43      document into an HTML segment.
     44    - L{split_fields()<ParsedRstDocstring.split_fields>} uses a
     45      L{_SplitFieldsTranslator} to divide the C{ParsedRstDocstring}'s
     46      document into its main body and its fields.  Special handling
     47      is done to account for consolidated fields.
     48    - L{summary()<ParsedRstDocstring.summary>} uses a
     49      L{_SummaryExtractor} to extract the first sentence from
     50      the C{ParsedRstDocstring}'s document.
     51    - L{to_plaintext()<ParsedRstDocstring.to_plaintext>} uses
     52      C{document.astext()} to convert the C{ParsedRstDocstring}'s
     53      document to plaintext.
     54
     55  @todo: Add ParsedRstDocstring.to_latex()
     56  @var CONSOLIDATED_FIELDS: A dictionary encoding the set of
     57  'consolidated fields' that can be used.  Each consolidated field is
     58  marked by a single tag, and contains a single bulleted list, where
     59  each list item starts with an identifier, marked as interpreted text
     60  (C{`...`}).  This module automatically splits these consolidated
     61  fields into individual fields.  The keys of C{CONSOLIDATED_FIELDS} are
     62  the names of possible consolidated fields; and the values are the
     63  names of the field tags that should be used for individual entries in
     64  the list.
     65  """
     66  __docformat__ = 'epytext en'
     67
     68  # Imports
     69  import re, os, os.path
     70  from xml.dom.minidom import *
     71
     72  from docutils.core import publish_string
     73  from docutils.writers import Writer
     74  from docutils.writers.html4css1 import HTMLTranslator, Writer as HTMLWriter
     75  from docutils.writers.latex2e import LaTeXTranslator, Writer as LaTeXWriter
     76  from docutils.readers.standalone import Reader as StandaloneReader
     77  from docutils.utils import new_document
     78  from docutils.nodes import NodeVisitor, Text, SkipChildren
     79  from docutils.nodes import SkipNode, TreeCopyVisitor
     80  from docutils.frontend import OptionParser
     81  from docutils.parsers.rst import directives, roles
     82  import docutils.nodes
     83  import docutils.transforms.frontmatter
     84  import docutils.transforms
     85  import docutils.utils
     86
     87  from epydoc.compat import * # Backwards compatibility
     88  from epydoc.markup import *
     89  from epydoc.apidoc import ModuleDoc, ClassDoc
     90  from epydoc.docwriter.dotgraph import *
     91  from epydoc.docwriter.xlink import ApiLinkReader
     92  from epydoc.markup.doctest import doctest_to_html, doctest_to_latex, \
     93                                    HTMLDoctestColorizer
     94
     95  #: A dictionary whose keys are the "consolidated fields" that are
     96  #: recognized by epydoc; and whose values are the corresponding epydoc
     97  #: field names that should be used for the individual fields.
     98  CONSOLIDATED_FIELDS = {
     99      'parameters': 'param',
    100      'arguments': 'arg',
    101      'exceptions': 'except',
    102      'variables': 'var',
    103      'ivariables': 'ivar',
    104      'cvariables': 'cvar',
    105      'groups': 'group',
    106      'types': 'type',
    107      'keywords': 'keyword',
    108      }
    109
    110  #: A list of consolidated fields whose bodies may be specified using a
    111  #: definition list, rather than a bulleted list.  For these fields, the
    112  #: 'classifier' for each term in the definition list is translated into
    113  #: a @type field.
    114  CONSOLIDATED_DEFLIST_FIELDS = ['param', 'arg', 'var', 'ivar', 'cvar', 'keyword']
    115
    116 -def parse_docstring(docstring, errors, **options):
    117      """
    118      Parse the given docstring, which is formatted using
    119      ReStructuredText; and return a L{ParsedDocstring} representation
    120      of its contents.
    121      @param docstring: The docstring to parse
    122      @type docstring: C{string}
    123      @param errors: A list where any errors generated during parsing
    124          will be stored.
    125      @type errors: C{list} of L{ParseError}
    126      @param options: Extra options.  Unknown options are ignored.
    127          Currently, no extra options are defined.
    128      @rtype: L{ParsedDocstring}
    129      """
    130      writer = _DocumentPseudoWriter()
    131      reader = _EpydocReader(errors) # Outputs errors to the list.
    132      publish_string(docstring, writer=writer, reader=reader,
    133                     settings_overrides={'report_level':10000,
    134                                         'halt_level':10000,
    135                                         'warning_stream':None})
    136      return ParsedRstDocstring(writer.document)
    137
    138 -class OptimizedReporter(docutils.utils.Reporter):
    139      """A reporter that ignores all debug messages.  This is used to
    140      shave a couple seconds off of epydoc's run time, since docutils
    141      isn't very fast about processing its own debug messages."""
    142 -    def debug(self, *args, **kwargs): pass
    143
    144 -class ParsedRstDocstring(ParsedDocstring):
    145      """
    146      An encoded version of a ReStructuredText docstring.  The contents
    147      of the docstring are encoded in the L{_document} instance
    148      variable.
    149
    150      @ivar _document: A ReStructuredText document, encoding the
    151          docstring.
    152      @type _document: C{docutils.nodes.document}
    153      """
    154 -    def __init__(self, document):
    155          """
    156          @type document: C{docutils.nodes.document}
    157          """
    158          self._document = document
    159
    160          # The default document reporter and transformer are not
    161          # pickle-able; so replace them with stubs that are.
    162          document.reporter = OptimizedReporter(
    163              document.reporter.source, 'SEVERE', 'SEVERE', '')
    164          document.transformer = docutils.transforms.Transformer(document)
    165
    166 -    def split_fields(self, errors=None):
    167          # Inherit docs
    168          if errors is None: errors = []
    169          visitor = _SplitFieldsTranslator(self._document, errors)
    170          self._document.walk(visitor)
    171          if len(self._document.children) > 0:
    172              return self, visitor.fields
    173          else:
    174              return None, visitor.fields
    175
    176 -    def summary(self):
    177          # Inherit docs
    178          visitor = _SummaryExtractor(self._document)
    179          try: self._document.walk(visitor)
    180          except docutils.nodes.NodeFound: pass
    181          return visitor.summary, bool(visitor.other_docs)
    182
    183  #     def concatenate(self, other):
    184  #         result = self._document.copy()
    185  #         for child in (self._document.get_children() +
    186  #                       other._document.get_children()):
    187  #             visitor = TreeCopyVisitor(self._document)
    188  #             child.walkabout(visitor)
    189  #             result.append(visitor.get_tree_copy())
    190  #         return ParsedRstDocstring(result)
    191
    192 -    def to_html(self, docstring_linker, directory=None,
    193                  docindex=None, context=None, **options):
    194          # Inherit docs
    195          visitor = _EpydocHTMLTranslator(self._document, docstring_linker,
    196                                          directory, docindex, context)
    197          self._document.walkabout(visitor)
    198          return ''.join(visitor.body)
    199
    200 -    def to_latex(self, docstring_linker, **options):
    201          # Inherit docs
    202          visitor = _EpydocLaTeXTranslator(self._document, docstring_linker)
    203          self._document.walkabout(visitor)
    204          return ''.join(visitor.body)
    205
    206 -    def to_plaintext(self, docstring_linker, **options):
    207          # This is should be replaced by something better:
    208          return self._document.astext()
    209
    210 -    def __repr__(self): return '<ParsedRstDocstring: ...>'
    211
    212 -    def index_terms(self):
    213          visitor = _TermsExtractor(self._document)
    214          self._document.walkabout(visitor)
    215          return visitor.terms
    216
    217 -class _EpydocReader(ApiLinkReader):
    218      """
    219      A reader that captures all errors that are generated by parsing,
    220      and appends them to a list.
    221      """
    222      # Remove the DocInfo transform, to ensure that :author: fields are
    223      # correctly handled.  This needs to be handled differently
    224      # depending on the version of docutils that's being used, because
    225      # the default_transforms attribute was deprecated & replaced by
    226      # get_transforms().
    227      version = [int(v) for v in docutils.__version__.split('.')]
    228      version += [ 0 ] * (3 - len(version))
    229      if version < [0,4,0]:
    230          default_transforms = list(ApiLinkReader.default_transforms)
    231          try: default_transforms.remove(docutils.transforms.frontmatter.DocInfo)
    232          except ValueError: pass
    233      else:
    234 -        def get_transforms(self):
    235              return [t for t in ApiLinkReader.get_transforms(self)
    236                      if t != docutils.transforms.frontmatter.DocInfo]
    237      del version
    238
    239 -    def __init__(self, errors):
    240          self._errors = errors
    241          ApiLinkReader.__init__(self)
    242
    243 -    def new_document(self):
    244          document = new_document(self.source.source_path, self.settings)
    245          # Capture all warning messages.
    246          document.reporter.attach_observer(self.report)
    247          # These are used so we know how to encode warning messages:
    248          self._encoding = document.reporter.encoding
    249          self._error_handler = document.reporter.error_handler
    250          # Return the new document.
    251          return document
    252
    253 -    def report(self, error):
    254          try: is_fatal = int(error['level']) > 2
    255          except: is_fatal = 1
    256          try: linenum = int(error['line'])
    257          except: linenum = None
    258
    259          msg = ''.join([c.astext().encode(self._encoding, self._error_handler)
    260                         for c in error])
    261
    262          self._errors.append(ParseError(msg, linenum, is_fatal))
    263
    264 -class _DocumentPseudoWriter(Writer):
    265      """
    266      A pseudo-writer for the docutils framework, that can be used to
    267      access the document itself.  The output of C{_DocumentPseudoWriter}
    268      is just an empty string; but after it has been used, the most
    269      recently processed document is available as the instance variable
    270      C{document}
    271
    272      @type document: C{docutils.nodes.document}
    273      @ivar document: The most recently processed document.
    274      """
    275 -    def __init__(self):
    276          self.document = None
    277          Writer.__init__(self)
    278
    279 -    def translate(self):
    280          self.output = ''
    281
    282 -class _SummaryExtractor(NodeVisitor):
    283      """
    284      A docutils node visitor that extracts the first sentence from
    285      the first paragraph in a document.
    286      """
    287 -    def __init__(self, document):
    288          NodeVisitor.__init__(self, document)
    289          self.summary = None
    290          self.other_docs = None
    291
    292 -    def visit_document(self, node):
    293          self.summary = None
    294
    295      _SUMMARY_RE = re.compile(r'(\s*[\w\W]*?\.)(\s|$)')
    296 -    def visit_paragraph(self, node):
    297          if self.summary is not None:
    298              # found a paragraph after the first one
    299              self.other_docs = True
    300              raise docutils.nodes.NodeFound('Found summary')
    301
    302          summary_pieces = []
    303
    304          # Extract the first sentence.
    305          for child in node:
    306              if isinstance(child, docutils.nodes.Text):
    307                  m = self._SUMMARY_RE.match(child.data)
    308                  if m:
    309                      summary_pieces.append(docutils.nodes.Text(m.group(1)))
    310                      other = child.data[m.end():]
    311                      if other and not other.isspace():
    312                          self.other_docs = True
    313                      break
    314              summary_pieces.append(child)
    315
    316          summary_doc = self.document.copy() # shallow copy
    317          summary_para = node.copy() # shallow copy
    318          summary_doc[:] = [summary_para]
    319          summary_para[:] = summary_pieces
    320          self.summary = ParsedRstDocstring(summary_doc)
    321
    322 -    def visit_field(self, node):
    323          raise SkipNode
    324
    325 -    def unknown_visit(self, node):
    326          'Ignore all unknown nodes'
    327
    328 -class _TermsExtractor(NodeVisitor):
    329      """
    330      A docutils node visitor that extracts the terms from documentation.
    331
    332      Terms are created using the C{:term:} interpreted text role.
    333      """
    334 -    def __init__(self, document):
    335          NodeVisitor.__init__(self, document)
    336
    337          self.terms = None
    338          """
    339          The terms currently found.
    340          @type: C{list}
    341          """
    342
    343 -    def visit_document(self, node):
    344          self.terms = []
    345          self._in_term = False
    346
    347 -    def visit_emphasis(self, node):
    348          if 'term' in node.get('classes'):
    349              self._in_term = True
    350
    351 -    def depart_emphasis(self, node):
    352          if 'term' in node.get('classes'):
    353              self._in_term = False
    354
    355 -    def visit_Text(self, node):
    356          if self._in_term:
    357              doc = self.document.copy()
    358              doc[:] = [node.copy()]
    359              self.terms.append(ParsedRstDocstring(doc))
    360
    361 -    def unknown_visit(self, node):
    362          'Ignore all unknown nodes'
    363
    364 -    def unknown_departure(self, node):
    365          'Ignore all unknown nodes'
    366
    367 -class _SplitFieldsTranslator(NodeVisitor):
    368      """
    369      A docutils translator that removes all fields from a document, and
    370      collects them into the instance variable C{fields}
    371
    372      @ivar fields: The fields of the most recently walked document.
    373      @type fields: C{list} of L{Field<markup.Field>}
    374      """
    375
    376      ALLOW_UNMARKED_ARG_IN_CONSOLIDATED_FIELD = True
    377      """If true, then consolidated fields are not required to mark
    378      arguments with C{`backticks`}.  (This is currently only
    379      implemented for consolidated fields expressed as definition lists;
    380      consolidated fields expressed as unordered lists still require
    381      backticks for now."""
    382
    383 -    def __init__(self, document, errors):
    384          NodeVisitor.__init__(self, document)
    385          self._errors = errors
    386          self.fields = []
    387          self._newfields = {}
    388
    389 -    def visit_document(self, node):
    390          self.fields = []
    391
    392 -    def visit_field(self, node):
    393          # Remove the field from the tree.
    394          node.parent.remove(node)
    395
    396          # Extract the field name & optional argument
    397          tag = node[0].astext().split(None, 1)
    398          tagname = tag[0]
    399          if len(tag)>1: arg = tag[1]
    400          else: arg = None
    401
    402          # Handle special fields:
    403          fbody = node[1]
    404          if arg is None:
    405              for (list_tag, entry_tag) in CONSOLIDATED_FIELDS.items():
    406                  if tagname.lower() == list_tag:
    407                      try:
    408                          self.handle_consolidated_field(fbody, entry_tag)
    409                          return
    410                      except ValueError, e:
    411                          estr = 'Unable to split consolidated field '
    412                          estr += '"%s" - %s' % (tagname, e)
    413                          self._errors.append(ParseError(estr, node.line,
    414                                                         is_fatal=0))
    415
    416                          # Use a @newfield to let it be displayed as-is.
    417                          if tagname.lower() not in self._newfields:
    418                              newfield = Field('newfield', tagname.lower(),
    419                                               parse(tagname, 'plaintext'))
    420                              self.fields.append(newfield)
    421                              self._newfields[tagname.lower()] = 1
    422
    423          self._add_field(tagname, arg, fbody)
    424
    425 -    def _add_field(self, tagname, arg, fbody):
    426          field_doc = self.document.copy()
    427          for child in fbody: field_doc.append(child)
    428          field_pdoc = ParsedRstDocstring(field_doc)
    429          self.fields.append(Field(tagname, arg, field_pdoc))
    430
    431 -    def visit_field_list(self, node):
    432          # Remove the field list from the tree.  The visitor will still walk
    433          # over the node's children.
    434          node.parent.remove(node)
    435
    436 -    def handle_consolidated_field(self, body, tagname):
    437          """
    438          Attempt to handle a consolidated section.
    439          """
    440          if len(body) != 1:
    441              raise ValueError('does not contain a single list.')
    442          elif body[0].tagname == 'bullet_list':
    443              self.handle_consolidated_bullet_list(body[0], tagname)
    444          elif (body[0].tagname == 'definition_list' and
    445                tagname in CONSOLIDATED_DEFLIST_FIELDS):
    446              self.handle_consolidated_definition_list(body[0], tagname)
    447          elif tagname in CONSOLIDATED_DEFLIST_FIELDS:
    448              raise ValueError('does not contain a bulleted list or '
    449                               'definition list.')
    450          else:
    451              raise ValueError('does not contain a bulleted list.')
    452
    453 -    def handle_consolidated_bullet_list(self, items, tagname):
    454          # Check the contents of the list.  In particular, each list
    455          # item should have the form:
    456          #   - `arg`: description...
    457          n = 0
    458          _BAD_ITEM = ("list item %d is not well formed.  Each item must "
    459                       "consist of a single marked identifier (e.g., `x`), "
    460                       "optionally followed by a colon or dash and a "
    461                       "description.")
    462          for item in items:
    463              n += 1
    464              if item.tagname != 'list_item' or len(item) == 0:
    465                  raise ValueError('bad bulleted list (bad child %d).' % n)
    466              if item[0].tagname != 'paragraph':
    467                  if item[0].tagname == 'definition_list':
    468                      raise ValueError(('list item %d contains a definition '+
    469                                        'list (it\'s probably indented '+
    470                                        'wrong).') % n)
    471                  else:
    472                      raise ValueError(_BAD_ITEM % n)
    473              if len(item[0]) == 0:
    474                  raise ValueError(_BAD_ITEM % n)
    475              if item[0][0].tagname != 'title_reference':
    476                  raise ValueError(_BAD_ITEM % n)
    477
    478          # Everything looks good; convert to multiple fields.
    479          for item in items:
    480              # Extract the arg
    481              arg = item[0][0].astext()
    482
    483              # Extract the field body, and remove the arg
    484              fbody = item[:]
    485              fbody[0] = fbody[0].copy()
    486              fbody[0][:] = item[0][1:]
    487
    488              # Remove the separating ":", if present
    489              if (len(fbody[0]) > 0 and
    490                  isinstance(fbody[0][0], docutils.nodes.Text)):
    491                  child = fbody[0][0]
    492                  if child.data[:1] in ':-':
    493                      child.data = child.data[1:].lstrip()
    494                  elif child.data[:2] in (' -', ' :'):
    495                      child.data = child.data[2:].lstrip()
    496
    497              # Wrap the field body, and add a new field
    498              self._add_field(tagname, arg, fbody)
    499
    500 -    def handle_consolidated_definition_list(self, items, tagname):
    501          # Check the list contents.
    502          n = 0
    503          _BAD_ITEM = ("item %d is not well formed.  Each item's term must "
    504                       "consist of a single marked identifier (e.g., `x`), "
    505                       "optionally followed by a space, colon, space, and "
    506                       "a type description.")
    507          for item in items:
    508              n += 1
    509              if (item.tagname != 'definition_list_item' or len(item) < 2 or
    510                  item[0].tagname != 'term' or
    511                  item[-1].tagname != 'definition'):
    512                  raise ValueError('bad definition list (bad child %d).' % n)
    513              if len(item) > 3:
    514                  raise ValueError(_BAD_ITEM % n)
    515              if not ((item[0][0].tagname == 'title_reference') or
    516                      (self.ALLOW_UNMARKED_ARG_IN_CONSOLIDATED_FIELD and
    517                       isinstance(item[0][0], docutils.nodes.Text))):
    518                  raise ValueError(_BAD_ITEM % n)
    519              for child in item[0][1:]:
    520                  if child.astext() != '':
    521                      raise ValueError(_BAD_ITEM % n)
    522
    523          # Extract it.
    524          for item in items:
    525              # The basic field.
    526              arg = item[0][0].astext()
    527              fbody = item[-1]
    528              self._add_field(tagname, arg, fbody)
    529              # If there's a classifier, treat it as a type.
    530              if len(item) == 3:
    531                  type_descr = item[1]
    532                  self._add_field('type', arg, type_descr)
    533
    534 -    def unknown_visit(self, node):
    535          'Ignore all unknown nodes'
    536
    537 -def latex_head_prefix():
    538      document = new_document('<fake>')
    539      translator = _EpydocLaTeXTranslator(document, None)
    540      return translator.head_prefix
    541
    542 -class _EpydocLaTeXTranslator(LaTeXTranslator):
    543      settings = None
    544 -    def __init__(self, document, docstring_linker):
    545          # Set the document's settings.
    546          if self.settings is None:
    547              settings = OptionParser([LaTeXWriter()]).get_default_values()
    548              settings.output_encoding = 'utf-8'
    549              self.__class__.settings = settings
    550          document.settings = self.settings
    551
    552          LaTeXTranslator.__init__(self, document)
    553          self._linker = docstring_linker
    554
    555          # Start at section level 3.  (Unfortunately, we now have to
    556          # set a private variable to make this work; perhaps the standard
    557          # latex translator should grow an official way to spell this?)
    558          self.section_level = 3
    559          self._section_number = [0]*self.section_level
    560
    561      # Handle interpreted text (crossreferences)
    562 -    def visit_title_reference(self, node):
    563          target = self.encode(node.astext())
    564          xref = self._linker.translate_identifier_xref(target, target)
    565          self.body.append(xref)
    566          raise SkipNode()
    567
    568 -    def visit_document(self, node): pass
    569 -    def depart_document(self, node): pass
    570
    571      # For now, just ignore dotgraphs. [XXX]
    572 -    def visit_dotgraph(self, node):
    573          log.warning("Ignoring dotgraph in latex output (dotgraph "
    574                      "rendering for latex not implemented yet).")
    575          raise SkipNode()
    576
    577 -    def visit_doctest_block(self, node):
    578          self.body.append(doctest_to_latex(node[0].astext()))
    579          raise SkipNode()
    580
    581 -class _EpydocHTMLTranslator(HTMLTranslator):
    582      settings = None
    583 -    def __init__(self, document, docstring_linker, directory,
    584                   docindex, context):
    585          self._linker = docstring_linker
    586          self._directory = directory
    587          self._docindex = docindex
    588          self._context = context
    589
    590          # Set the document's settings.
    591          if self.settings is None:
    592              settings = OptionParser([HTMLWriter()]).get_default_values()
    593              self.__class__.settings = settings
    594          document.settings = self.settings
    595
    596          # Call the parent constructor.
    597          HTMLTranslator.__init__(self, document)
    598
    599      # Handle interpreted text (crossreferences)
    600 -    def visit_title_reference(self, node):
    601          target = self.encode(node.astext())
    602          xref = self._linker.translate_identifier_xref(target, target)
    603          self.body.append(xref)
    604          raise SkipNode()
    605
    606 -    def should_be_compact_paragraph(self, node):
    607          if self.document.children == [node]:
    608              return True
    609          else:
    610              return HTMLTranslator.should_be_compact_paragraph(self, node)
    611
    612 -    def visit_document(self, node): pass
    613 -    def depart_document(self, node): pass
    614
    615 -    def starttag(self, node, tagname, suffix='\n', **attributes):
    616          """
    617          This modified version of starttag makes a few changes to HTML
    618          tags, to prevent them from conflicting with epydoc.  In particular:
    619            - existing class attributes are prefixed with C{'rst-'}
    620            - existing names are prefixed with C{'rst-'}
    621            - hrefs starting with C{'#'} are prefixed with C{'rst-'}
    622            - hrefs not starting with C{'#'} are given target='_top'
    623            - all headings (C{<hM{n}>}) are given the css class C{'heading'}
    624          """
    625          # Get the list of all attribute dictionaries we need to munge.
    626          attr_dicts = [attributes]
    627          if isinstance(node, docutils.nodes.Node):
    628              attr_dicts.append(node.attributes)
    629          if isinstance(node, dict):
    630              attr_dicts.append(node)
    631          # Munge each attribute dictionary.  Unfortunately, we need to
    632          # iterate through attributes one at a time because some
    633          # versions of docutils don't case-normalize attributes.
    634          for attr_dict in attr_dicts:
    635              for (key, val) in attr_dict.items():
    636                  # Prefix all CSS classes with "rst-"; and prefix all
    637                  # names with "rst-" to avoid conflicts.
    638                  if key.lower() in ('class', 'id', 'name'):
    639                      attr_dict[key] = 'rst-%s' % val
    640                  elif key.lower() in ('classes', 'ids', 'names'):
    641                      attr_dict[key] = ['rst-%s' % cls for cls in val]
    642                  elif key.lower() == 'href':
    643                      if attr_dict[key][:1]=='#':
    644                          attr_dict[key] = '#rst-%s' % attr_dict[key][1:]
    645                      else:
    646                          # If it's an external link, open it in a new
    647                          # page.
    648                          attr_dict['target'] = '_top'
    649
    650          # For headings, use class="heading"
    651          if re.match(r'^h\d+$', tagname):
    652              attributes['class'] = ' '.join([attributes.get('class',''),
    653                                              'heading']).strip()
    654
    655          return HTMLTranslator.starttag(self, node, tagname, suffix,
    656                                         **attributes)
    657
    658 -    def visit_dotgraph(self, node):
    659          if self._directory is None: return # [xx] warning?
    660
    661          # Generate the graph.
    662          graph = node.graph(self._docindex, self._context, self._linker)
    663          if graph is None: return
    664
    665          # Write the graph.
    666          image_url = '%s.gif' % graph.uid
    667          image_file = os.path.join(self._directory, image_url)
    668          self.body.append(graph.to_html(image_file, image_url))
    669          raise SkipNode()
    670
    671 -    def visit_doctest_block(self, node):
    672          pysrc = node[0].astext()
    673          if node.get('codeblock'):
    674              self.body.append(HTMLDoctestColorizer().colorize_codeblock(pysrc))
    675          else:
    676              self.body.append(doctest_to_html(pysrc))
    677          raise SkipNode()
    678
    679 -    def visit_emphasis(self, node):
    680          # Generate a corrent index term anchor
    681          if 'term' in node.get('classes') and node.children:
    682              doc = self.document.copy()
    683              doc[:] = [node.children[0].copy()]
    684              self.body.append(
    685                  self._linker.translate_indexterm(ParsedRstDocstring(doc)))
    686              raise SkipNode()
    687
    688          HTMLTranslator.visit_emphasis(self, node)
    689
    690 -def python_code_directive(name, arguments, options, content, lineno,
    691                            content_offset, block_text, state, state_machine):
    692      """
    693      A custom restructuredtext directive which can be used to display
    694      syntax-highlighted Python code blocks.  This directive takes no
    695      arguments, and the body should contain only Python code.  This
    696      directive can be used instead of doctest blocks when it is
    697      inconvenient to list prompts on each line, or when you would
    698      prefer that the output not contain prompts (e.g., to make
    699      copy/paste easier).
    700      """
    701      required_arguments = 0
    702      optional_arguments = 0
    703
    704      text = '\n'.join(content)
    705      node = docutils.nodes.doctest_block(text, text, codeblock=True)
    706      return [ node ]
    707
    708  python_code_directive.arguments = (0, 0, 0)
    709  python_code_directive.content = True
    710
    711  directives.register_directive('python', python_code_directive)
    712
    713 -def term_role(name, rawtext, text, lineno, inliner,
    714              options={}, content=[]):
    715
    716      text = docutils.utils.unescape(text)
    717      node = docutils.nodes.emphasis(rawtext, text, **options)
    718      node.attributes['classes'].append('term')
    719
    720      return [node], []
    721
    722  roles.register_local_role('term', term_role)
    723
    724  ######################################################################
    725  #{ Graph Generation Directives
    726  ######################################################################
    727  # See http://docutils.sourceforge.net/docs/howto/rst-directives.html
    728
    729 -class dotgraph(docutils.nodes.image):
    730      """
    731      A custom docutils node that should be rendered using Graphviz dot.
    732      This node does not directly store the graph; instead, it stores a
    733      pointer to a function that can be used to generate the graph.
    734      This allows the graph to be built based on information that might
    735      not be available yet at parse time.  This graph generation
    736      function has the following signature:
    737
    738          >>> def generate_graph(docindex, context, linker, *args):
    739          ...     'generates and returns a new DotGraph'
    740
    741      Where C{docindex} is a docindex containing the documentation that
    742      epydoc has built; C{context} is the C{APIDoc} whose docstring
    743      contains this dotgraph node; C{linker} is a L{DocstringLinker}
    744      that can be used to resolve crossreferences; and C{args} is any
    745      extra arguments that are passed to the C{dotgraph} constructor.
    746      """
    747 -    def __init__(self, generate_graph_func, *generate_graph_args):
    748          docutils.nodes.image.__init__(self)
    749          self.graph_func = generate_graph_func
    750          self.args = generate_graph_args
    751 -    def graph(self, docindex, context, linker):
    752          return self.graph_func(docindex, context, linker, *self.args)
    753
    754 -def _dir_option(argument):
    755      """A directive option spec for the orientation of a graph."""
    756      argument = argument.lower().strip()
    757      if argument == 'right': return 'LR'
    758      if argument == 'left': return 'RL'
    759      if argument == 'down': return 'TB'
    760      if argument == 'up': return 'BT'
    761      raise ValueError('%r unknown; choose from left, right, up, down' %
    762                       argument)
    763
    764 -def digraph_directive(name, arguments, options, content, lineno,
    765                        content_offset, block_text, state, state_machine):
    766      """
    767      A custom restructuredtext directive which can be used to display
    768      Graphviz dot graphs.  This directive takes a single argument,
    769      which is used as the graph's name.  The contents of the directive
    770      are used as the body of the graph.  Any href attributes whose
    771      value has the form <name> will be replaced by the URL of the object
    772      with that name.  Here's a simple example::
    773
    774       .. digraph:: example_digraph
    775         a -> b -> c
    776         c -> a [dir=\"none\"]
    777      """
    778      if arguments: title = arguments[0]
    779      else: title = ''
    780      return [ dotgraph(_construct_digraph, title, options.get('caption'),
    781                      '\n'.join(content)) ]
    782  digraph_directive.arguments = (0, 1, True)
    783  digraph_directive.options = {'caption': directives.unchanged}
    784  digraph_directive.content = True
    785  directives.register_directive('digraph', digraph_directive)
    786
    787 -def _construct_digraph(docindex, context, linker, title, caption,
    788                         body):
    789      """Graph generator for L{digraph_directive}"""
    790      graph = DotGraph(title, body, caption=caption)
    791      graph.link(linker)
    792      return graph
    793
    794 -def classtree_directive(name, arguments, options, content, lineno,
    795                          content_offset, block_text, state, state_machine):
    796      """
    797      A custom restructuredtext directive which can be used to
    798      graphically display a class hierarchy.  If one or more arguments
    799      are given, then those classes and all their descendants will be
    800      displayed.  If no arguments are given, and the directive is in a
    801      class's docstring, then that class and all its descendants will be
    802      displayed.  It is an error to use this directive with no arguments
    803      in a non-class docstring.
    804
    805      Options:
    806        - C{:dir:} -- Specifies the orientation of the graph.  One of
    807          C{down}, C{right} (default), C{left}, C{up}.
    808      """
    809      return [ dotgraph(_construct_classtree, arguments, options) ]
    810  classtree_directive.arguments = (0, 1, True)
    811  classtree_directive.options = {'dir': _dir_option}
    812  classtree_directive.content = False
    813  directives.register_directive('classtree', classtree_directive)
    814
    815 -def _construct_classtree(docindex, context, linker, arguments, options):
    816      """Graph generator for L{classtree_directive}"""
    817      if len(arguments) == 1:
    818          bases = [docindex.find(name, context) for name in
    819                   arguments[0].replace(',',' ').split()]
    820          bases = [d for d in bases if isinstance(d, ClassDoc)]
    821      elif isinstance(context, ClassDoc):
    822          bases = [context]
    823      else:
    824          log.warning("Could not construct class tree: you must "
    825                      "specify one or more base classes.")
    826          return None
    827
    828      return class_tree_graph(bases, linker, context, **options)
    829
    830 -def packagetree_directive(name, arguments, options, content, lineno,
    831                          content_offset, block_text, state, state_machine):
    832      """
    833      A custom restructuredtext directive which can be used to
    834      graphically display a package hierarchy.  If one or more arguments
    835      are given, then those packages and all their submodules will be
    836      displayed.  If no arguments are given, and the directive is in a
    837      package's docstring, then that package and all its submodules will
    838      be displayed.  It is an error to use this directive with no
    839      arguments in a non-package docstring.
    840
    841      Options:
    842        - C{:dir:} -- Specifies the orientation of the graph.  One of
    843          C{down}, C{right} (default), C{left}, C{up}.
    844      """
    845      return [ dotgraph(_construct_packagetree, arguments, options) ]
    846  packagetree_directive.arguments = (0, 1, True)
    847  packagetree_directive.options = {
    848    'dir': _dir_option,
    849    'style': lambda a:directives.choice(a.lower(), ('uml', 'tree'))}
    850  packagetree_directive.content = False
    851  directives.register_directive('packagetree', packagetree_directive)
    852
    853 -def _construct_packagetree(docindex, context, linker, arguments, options):
    854      """Graph generator for L{packagetree_directive}"""
    855      if len(arguments) == 1:
    856          packages = [docindex.find(name, context) for name in
    857                      arguments[0].replace(',',' ').split()]
    858          packages = [d for d in packages if isinstance(d, ModuleDoc)]
    859      elif isinstance(context, ModuleDoc):
    860          packages = [context]
    861      else:
    862          log.warning("Could not construct package tree: you must "
    863                      "specify one or more root packages.")
    864          return None
    865
    866      return package_tree_graph(packages, linker, context, **options)
    867
    868 -def importgraph_directive(name, arguments, options, content, lineno,
    869                          content_offset, block_text, state, state_machine):
    870      return [ dotgraph(_construct_importgraph, arguments, options) ]
    871  importgraph_directive.arguments = (0, 1, True)
    872  importgraph_directive.options = {'dir': _dir_option}
    873  importgraph_directive.content = False
    874  directives.register_directive('importgraph', importgraph_directive)
    875
    876 -def _construct_importgraph(docindex, context, linker, arguments, options):
    877      """Graph generator for L{importgraph_directive}"""
    878      if len(arguments) == 1:
    879          modules = [ docindex.find(name, context)
    880                      for name in arguments[0].replace(',',' ').split() ]
    881          modules = [d for d in modules if isinstance(d, ModuleDoc)]
    882      else:
    883          modules = [d for d in docindex.root if isinstance(d, ModuleDoc)]
    884
    885      return import_graph(modules, docindex, linker, context, **options)
    886
    887 -def callgraph_directive(name, arguments, options, content, lineno,
    888                          content_offset, block_text, state, state_machine):
    889      return [ dotgraph(_construct_callgraph, arguments, options) ]
    890  callgraph_directive.arguments = (0, 1, True)
    891  callgraph_directive.options = {'dir': _dir_option,
    892                                   'add_callers': directives.flag,
    893                                   'add_callees': directives.flag}
    894  callgraph_directive.content = False
    895  directives.register_directive('callgraph', callgraph_directive)
    896
    897 -def _construct_callgraph(docindex, context, linker, arguments, options):
    898      """Graph generator for L{callgraph_directive}"""
    899      if len(arguments) == 1:
    900          docs = [docindex.find(name, context) for name in
    901                   arguments[0].replace(',',' ').split()]
    902          docs = [doc for doc in docs if doc is not None]
    903      else:
    904          docs = [context]
    905      return call_graph(docs, docindex, linker, context, **options)
    906