| # $Id: parts.py 6385 2010-08-13 12:17:01Z milde $ |
| # Authors: David Goodger <goodger@python.org>; Dmitry Jemerov |
| # Copyright: This module has been placed in the public domain. |
| |
| """ |
| Directives for document parts. |
| """ |
| |
| __docformat__ = 'reStructuredText' |
| |
| from docutils import nodes, languages |
| from docutils.transforms import parts |
| from docutils.parsers.rst import Directive |
| from docutils.parsers.rst import directives |
| |
| |
| class Contents(Directive): |
| |
| """ |
| Table of contents. |
| |
| The table of contents is generated in two passes: initial parse and |
| transform. During the initial parse, a 'pending' element is generated |
| which acts as a placeholder, storing the TOC title and any options |
| internally. At a later stage in the processing, the 'pending' element is |
| replaced by a 'topic' element, a title and the table of contents proper. |
| """ |
| |
| backlinks_values = ('top', 'entry', 'none') |
| |
| def backlinks(arg): |
| value = directives.choice(arg, Contents.backlinks_values) |
| if value == 'none': |
| return None |
| else: |
| return value |
| |
| required_arguments = 0 |
| optional_arguments = 1 |
| final_argument_whitespace = True |
| option_spec = {'depth': directives.nonnegative_int, |
| 'local': directives.flag, |
| 'backlinks': backlinks, |
| 'class': directives.class_option} |
| |
| def run(self): |
| if not (self.state_machine.match_titles |
| or isinstance(self.state_machine.node, nodes.sidebar)): |
| raise self.error('The "%s" directive may not be used within ' |
| 'topics or body elements.' % self.name) |
| document = self.state_machine.document |
| language = languages.get_language(document.settings.language_code) |
| if self.arguments: |
| title_text = self.arguments[0] |
| text_nodes, messages = self.state.inline_text(title_text, |
| self.lineno) |
| title = nodes.title(title_text, '', *text_nodes) |
| else: |
| messages = [] |
| if 'local' in self.options: |
| title = None |
| else: |
| title = nodes.title('', language.labels['contents']) |
| topic = nodes.topic(classes=['contents']) |
| topic['classes'] += self.options.get('class', []) |
| # the latex2e writer needs source and line for a warning: |
| src, srcline = self.state_machine.get_source_and_line() |
| topic.source = src |
| topic.line = srcline - 1 |
| if 'local' in self.options: |
| topic['classes'].append('local') |
| if title: |
| name = title.astext() |
| topic += title |
| else: |
| name = language.labels['contents'] |
| name = nodes.fully_normalize_name(name) |
| if not document.has_name(name): |
| topic['names'].append(name) |
| document.note_implicit_target(topic) |
| pending = nodes.pending(parts.Contents, rawsource=self.block_text) |
| pending.details.update(self.options) |
| document.note_pending(pending) |
| topic += pending |
| return [topic] + messages |
| |
| |
| class Sectnum(Directive): |
| |
| """Automatic section numbering.""" |
| |
| option_spec = {'depth': int, |
| 'start': int, |
| 'prefix': directives.unchanged_required, |
| 'suffix': directives.unchanged_required} |
| |
| def run(self): |
| pending = nodes.pending(parts.SectNum) |
| pending.details.update(self.options) |
| self.state_machine.document.note_pending(pending) |
| return [pending] |
| |
| |
| class Header(Directive): |
| |
| """Contents of document header.""" |
| |
| has_content = True |
| |
| def run(self): |
| self.assert_has_content() |
| header = self.state_machine.document.get_decoration().get_header() |
| self.state.nested_parse(self.content, self.content_offset, header) |
| return [] |
| |
| |
| class Footer(Directive): |
| |
| """Contents of document footer.""" |
| |
| has_content = True |
| |
| def run(self): |
| self.assert_has_content() |
| footer = self.state_machine.document.get_decoration().get_footer() |
| self.state.nested_parse(self.content, self.content_offset, footer) |
| return [] |
