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 [] |
|