[3] | 1 | # Author: David Goodger, Dmitry Jemerov |
---|
| 2 | # Contact: goodger@users.sourceforge.net |
---|
| 3 | # Revision: $Revision: 3439 $ |
---|
| 4 | # Date: $Date: 2005-06-06 03:20:35 +0200 (Mon, 06 Jun 2005) $ |
---|
| 5 | # Copyright: This module has been placed in the public domain. |
---|
| 6 | |
---|
| 7 | """ |
---|
| 8 | Directives for document parts. |
---|
| 9 | """ |
---|
| 10 | |
---|
| 11 | __docformat__ = 'reStructuredText' |
---|
| 12 | |
---|
| 13 | from docutils import nodes, languages |
---|
| 14 | from docutils.transforms import parts |
---|
| 15 | from docutils.parsers.rst import directives |
---|
| 16 | |
---|
| 17 | |
---|
| 18 | backlinks_values = ('top', 'entry', 'none') |
---|
| 19 | |
---|
| 20 | def backlinks(arg): |
---|
| 21 | value = directives.choice(arg, backlinks_values) |
---|
| 22 | if value == 'none': |
---|
| 23 | return None |
---|
| 24 | else: |
---|
| 25 | return value |
---|
| 26 | |
---|
| 27 | def contents(name, arguments, options, content, lineno, |
---|
| 28 | content_offset, block_text, state, state_machine): |
---|
| 29 | """ |
---|
| 30 | Table of contents. |
---|
| 31 | |
---|
| 32 | The table of contents is generated in two passes: initial parse and |
---|
| 33 | transform. During the initial parse, a 'pending' element is generated |
---|
| 34 | which acts as a placeholder, storing the TOC title and any options |
---|
| 35 | internally. At a later stage in the processing, the 'pending' element is |
---|
| 36 | replaced by a 'topic' element, a title and the table of contents proper. |
---|
| 37 | """ |
---|
| 38 | if not (state_machine.match_titles |
---|
| 39 | or isinstance(state_machine.node, nodes.sidebar)): |
---|
| 40 | error = state_machine.reporter.error( |
---|
| 41 | 'The "%s" directive may not be used within topics ' |
---|
| 42 | 'or body elements.' % name, |
---|
| 43 | nodes.literal_block(block_text, block_text), line=lineno) |
---|
| 44 | return [error] |
---|
| 45 | document = state_machine.document |
---|
| 46 | language = languages.get_language(document.settings.language_code) |
---|
| 47 | if arguments: |
---|
| 48 | title_text = arguments[0] |
---|
| 49 | text_nodes, messages = state.inline_text(title_text, lineno) |
---|
| 50 | title = nodes.title(title_text, '', *text_nodes) |
---|
| 51 | else: |
---|
| 52 | messages = [] |
---|
| 53 | if options.has_key('local'): |
---|
| 54 | title = None |
---|
| 55 | else: |
---|
| 56 | title = nodes.title('', language.labels['contents']) |
---|
| 57 | topic = nodes.topic(classes=['contents']) |
---|
| 58 | topic['classes'] += options.get('class', []) |
---|
| 59 | if options.has_key('local'): |
---|
| 60 | topic['classes'].append('local') |
---|
| 61 | if title: |
---|
| 62 | name = title.astext() |
---|
| 63 | topic += title |
---|
| 64 | else: |
---|
| 65 | name = language.labels['contents'] |
---|
| 66 | name = nodes.fully_normalize_name(name) |
---|
| 67 | if not document.has_name(name): |
---|
| 68 | topic['names'].append(name) |
---|
| 69 | document.note_implicit_target(topic) |
---|
| 70 | pending = nodes.pending(parts.Contents, rawsource=block_text) |
---|
| 71 | pending.details.update(options) |
---|
| 72 | document.note_pending(pending) |
---|
| 73 | topic += pending |
---|
| 74 | return [topic] + messages |
---|
| 75 | |
---|
| 76 | contents.arguments = (0, 1, 1) |
---|
| 77 | contents.options = {'depth': directives.nonnegative_int, |
---|
| 78 | 'local': directives.flag, |
---|
| 79 | 'backlinks': backlinks, |
---|
| 80 | 'class': directives.class_option} |
---|
| 81 | |
---|
| 82 | def sectnum(name, arguments, options, content, lineno, |
---|
| 83 | content_offset, block_text, state, state_machine): |
---|
| 84 | """Automatic section numbering.""" |
---|
| 85 | pending = nodes.pending(parts.SectNum) |
---|
| 86 | pending.details.update(options) |
---|
| 87 | state_machine.document.note_pending(pending) |
---|
| 88 | return [pending] |
---|
| 89 | |
---|
| 90 | sectnum.options = {'depth': int, |
---|
| 91 | 'start': int, |
---|
| 92 | 'prefix': directives.unchanged_required, |
---|
| 93 | 'suffix': directives.unchanged_required} |
---|
| 94 | |
---|
| 95 | def header_footer(node, name, arguments, options, content, lineno, |
---|
| 96 | content_offset, block_text, state, state_machine): |
---|
| 97 | """Contents of document header or footer.""" |
---|
| 98 | if not content: |
---|
| 99 | warning = state_machine.reporter.warning( |
---|
| 100 | 'Content block expected for the "%s" directive; none found.' |
---|
| 101 | % name, nodes.literal_block(block_text, block_text), |
---|
| 102 | line=lineno) |
---|
| 103 | node.append(nodes.paragraph( |
---|
| 104 | '', 'Problem with the "%s" directive: no content supplied.' % name)) |
---|
| 105 | return [warning] |
---|
| 106 | text = '\n'.join(content) |
---|
| 107 | state.nested_parse(content, content_offset, node) |
---|
| 108 | return [] |
---|
| 109 | |
---|
| 110 | def header(name, arguments, options, content, lineno, |
---|
| 111 | content_offset, block_text, state, state_machine): |
---|
| 112 | decoration = state_machine.document.get_decoration() |
---|
| 113 | node = decoration.get_header() |
---|
| 114 | return header_footer(node, name, arguments, options, content, lineno, |
---|
| 115 | content_offset, block_text, state, state_machine) |
---|
| 116 | |
---|
| 117 | header.content = 1 |
---|
| 118 | |
---|
| 119 | def footer(name, arguments, options, content, lineno, |
---|
| 120 | content_offset, block_text, state, state_machine): |
---|
| 121 | decoration = state_machine.document.get_decoration() |
---|
| 122 | node = decoration.get_footer() |
---|
| 123 | return header_footer(node, name, arguments, options, content, lineno, |
---|
| 124 | content_offset, block_text, state, state_machine) |
---|
| 125 | |
---|
| 126 | footer.content = 1 |
---|