sandbox/screenplay/screenplay.py

   1 # $Id$
   2 # Authors: Jeffrey C. Jacobs
   3 # Copyright: This module has been placed in the public domain.
   4
   5 """
   6 Directives for screenplays.
   7 """
   8
   9 __docformat__ = 'reStructuredText'
  10
  11 from docutils import nodes, languages
  12 from docutils.transforms import parts
  13 from docutils.parsers.rst import Directive
  14 from docutils.parsers.rst import directives
  15
  16
  17 class Screenplay(Directive):
  18
  19     """
  20     Use Screenplay formatting.
  21
  22     The screenplay format is a post-processing transform to change
  23     certain document nodes and classes to be compatible for styling with
  24     the various output writers.  During the initial parse, a 'pending'
  25     element is generated which acts as a placeholder, storing any
  26     options internally.  At a later stage in the processing, the
  27     'pending' element is removed and the entire doctree is scanned for
  28     any elements which need to be transformed.
  29     """
  30     # TODO: Replace with code as described by class documentation
  31
  32     backlinks_values = ('top', 'entry', 'none')
  33
  34     def backlinks(arg):
  35         value = directives.choice(arg, Contents.backlinks_values)
  36         if value == 'none':
  37             return None
  38         else:
  39             return value
  40
  41     optional_arguments = 1
  42     final_argument_whitespace = True
  43     option_spec = {'depth': directives.nonnegative_int,
  44                    'local': directives.flag,
  45                    'backlinks': backlinks,
  46                    'class': directives.class_option}
  47
  48     def run(self):
  49         if not (self.state_machine.match_titles
  50                 or isinstance(self.state_machine.node, nodes.sidebar)):
  51             raise self.error('The "%s" directive may not be used within '
  52                              'topics or body elements.' % self.name)
  53         document = self.state_machine.document
  54         language = languages.get_language(document.settings.language_code,
  55                                           document.reporter)
  56         if self.arguments:
  57             title_text = self.arguments[0]
  58             text_nodes, messages = self.state.inline_text(title_text,
  59                                                           self.lineno)
  60             title = nodes.title(title_text, '', *text_nodes)
  61         else:
  62             messages = []
  63             if 'local' in self.options:
  64                 title = None
  65             else:
  66                 title = nodes.title('', language.labels['contents'])
  67         topic = nodes.topic(classes=['contents'])
  68         topic['classes'] += self.options.get('class', [])
  69         # the latex2e writer needs source and line for a warning:
  70         topic.source, topic.line = self.state_machine.get_source_and_line()
  71         topic.line -= 1
  72         if 'local' in self.options:
  73             topic['classes'].append('local')
  74         if title:
  75             name = title.astext()
  76             topic += title
  77         else:
  78             name = language.labels['contents']
  79         name = nodes.fully_normalize_name(name)
  80         if not document.has_name(name):
  81             topic['names'].append(name)
  82         document.note_implicit_target(topic)
  83         pending = nodes.pending(parts.Contents, rawsource=self.block_text)
  84         pending.details.update(self.options)
  85         document.note_pending(pending)
  86         topic += pending
  87         return [topic] + messages
  88