docutils/parsers/rst/directives/parts.py

   1 # $Id$
   2 # Authors: David Goodger <goodger@python.org>; Dmitry Jemerov
   3 # Copyright: This module has been placed in the public domain.
   4
   5 """
   6 Directives for document parts.
   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 Contents(Directive):
  18
  19     """
  20     Table of contents.
  21
  22     The table of contents is generated in two passes: initial parse and
  23     transform.  During the initial parse, a 'pending' element is generated
  24     which acts as a placeholder, storing the TOC title and any options
  25     internally.  At a later stage in the processing, the 'pending' element is
  26     replaced by a 'topic' element, a title and the table of contents proper.
  27     """
  28
  29     backlinks_values = ('top', 'entry', 'none')
  30
  31     def backlinks(arg):
  32         value = directives.choice(arg, Contents.backlinks_values)
  33         if value == 'none':
  34             return None
  35         else:
  36             return value
  37
  38     optional_arguments = 1
  39     final_argument_whitespace = True
  40     option_spec = {'depth': directives.nonnegative_int,
  41                    'local': directives.flag,
  42                    'backlinks': backlinks,
  43                    'class': directives.class_option}
  44
  45     def run(self):
  46         if not (self.state_machine.match_titles
  47                 or isinstance(self.state_machine.node, nodes.sidebar)):
  48             raise self.error('The "%s" directive may not be used within '
  49                              'topics or body elements.' % self.name)
  50         document = self.state_machine.document
  51         language = languages.get_language(document.settings.language_code,
  52                                           document.reporter)
  53         if self.arguments:
  54             title_text = self.arguments[0]
  55             text_nodes, messages = self.state.inline_text(title_text,
  56                                                           self.lineno)
  57             title = nodes.title(title_text, '', *text_nodes)
  58         else:
  59             messages = []
  60             if 'local' in self.options:
  61                 title = None
  62             else:
  63                 title = nodes.title('', language.labels['contents'])
  64         topic = nodes.topic(classes=['contents'])
  65         topic['classes'] += self.options.get('class', [])
  66         # the latex2e writer needs source and line for a warning:
  67         src, srcline = self.state_machine.get_source_and_line()
  68         topic.source = src
  69         topic.line = srcline - 1
  70         if 'local' in self.options:
  71             topic['classes'].append('local')
  72         if title:
  73             name = title.astext()
  74             topic += title
  75         else:
  76             name = language.labels['contents']
  77         name = nodes.fully_normalize_name(name)
  78         if not document.has_name(name):
  79             topic['names'].append(name)
  80         document.note_implicit_target(topic)
  81         pending = nodes.pending(parts.Contents, rawsource=self.block_text)
  82         pending.details.update(self.options)
  83         document.note_pending(pending)
  84         topic += pending
  85         return [topic] + messages
  86
  87
  88 class Sectnum(Directive):
  89
  90     """Automatic section numbering."""
  91
  92     option_spec = {'depth': int,
  93                    'start': int,
  94                    'prefix': directives.unchanged_required,
  95                    'suffix': directives.unchanged_required}
  96
  97     def run(self):
  98         pending = nodes.pending(parts.SectNum)
  99         pending.details.update(self.options)
 100         self.state_machine.document.note_pending(pending)
 101         return [pending]
 102
 103
 104 class Header(Directive):
 105
 106     """Contents of document header."""
 107
 108     has_content = True
 109
 110     def run(self):
 111         self.assert_has_content()
 112         header = self.state_machine.document.get_decoration().get_header()
 113         self.state.nested_parse(self.content, self.content_offset, header)
 114         return []
 115
 116
 117 class Footer(Directive):
 118
 119     """Contents of document footer."""
 120
 121     has_content = True
 122
 123     def run(self):
 124         self.assert_has_content()
 125         footer = self.state_machine.document.get_decoration().get_footer()
 126         self.state.nested_parse(self.content, self.content_offset, footer)
 127         return []