1 # $Id: parts.py 4667 2006-07-12 21:40:56Z wiemann $

     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     required_arguments = 0

    39     optional_arguments = 1

    40     final_argument_whitespace = True

    41     option_spec = {'depth': directives.nonnegative_int,

    42                    'local': directives.flag,

    43                    'backlinks': backlinks,

    44                    'class': directives.class_option}

    45     

    46     def run(self):

    47         if not (self.state_machine.match_titles

    48                 or isinstance(self.state_machine.node, nodes.sidebar)):

    49             raise self.error('The "%s" directive may not be used within '

    50                              'topics or body elements.' % self.name)

    51         document = self.state_machine.document

    52         language = languages.get_language(document.settings.language_code)

    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 self.options.has_key('local'):

    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         if self.options.has_key('local'):

    67             topic['classes'].append('local')

    68         if title:

    69             name = title.astext()

    70             topic += title

    71         else:

    72             name = language.labels['contents']

    73         name = nodes.fully_normalize_name(name)

    74         if not document.has_name(name):

    75             topic['names'].append(name)

    76         document.note_implicit_target(topic)

    77         pending = nodes.pending(parts.Contents, rawsource=self.block_text)

    78         pending.details.update(self.options)

    79         document.note_pending(pending)

    80         topic += pending

    81         return [topic] + messages

    82 

    83 

    84 class Sectnum(Directive):

    85 

    86     """Automatic section numbering."""

    87 

    88     option_spec = {'depth': int,

    89                    'start': int,

    90                    'prefix': directives.unchanged_required,

    91                    'suffix': directives.unchanged_required}

    92 

    93     def run(self):

    94         pending = nodes.pending(parts.SectNum)

    95         pending.details.update(self.options)

    96         self.state_machine.document.note_pending(pending)

    97         return [pending]

    98 

    99 

   100 class Header(Directive):

   101 

   102     """Contents of document header."""

   103 

   104     has_content = True

   105 

   106     def run(self):

   107         self.assert_has_content()

   108         header = self.state_machine.document.get_decoration().get_header()

   109         self.state.nested_parse(self.content, self.content_offset, header)

   110         return []

   111 

   112 

   113 class Footer(Directive):

   114 

   115     """Contents of document footer."""

   116 

   117     has_content = True

   118 

   119     def run(self):

   120         self.assert_has_content()

   121         footer = self.state_machine.document.get_decoration().get_footer()

   122         self.state.nested_parse(self.content, self.content_offset, footer)

   123         return []