Edit File: parts.py
# $Id: parts.py 8993 2022-01-29 13:20:04Z 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 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, document.reporter) 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: topic.source, topic.line = self.state_machine.get_source_and_line() topic.line -= 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 []
Back to File Manager