2 # Authors: Jeffrey C. Jacobs
3 # Copyright: This module has been placed in the public domain.
6 Directives for screenplays.
9 __docformat__
= 'reStructuredText'
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
17 class Screenplay(Directive
):
20 Use Screenplay formatting.
22 The screenplay format is a post-processing transform to change
23 certain document nodes and classes to be compatible for styling with
24 the various output writers. During the initial parse, a 'pending'
25 element is generated which acts as a placeholder, storing any
26 options internally. At a later stage in the processing, the
27 'pending' element is removed and the entire doctree is scanned for
28 any elements which need to be transformed.
30 # TODO: Replace with code as described by class documentation
32 backlinks_values
= ('top', 'entry', 'none')
35 value
= directives
.choice(arg
, Contents
.backlinks_values
)
41 optional_arguments
= 1
42 final_argument_whitespace
= True
43 option_spec
= {'depth': directives
.nonnegative_int
,
44 'local': directives
.flag
,
45 'backlinks': backlinks
,
46 'class': directives
.class_option
}
49 if not (self
.state_machine
.match_titles
50 or isinstance(self
.state_machine
.node
, nodes
.sidebar
)):
51 raise self
.error('The "%s" directive may not be used within '
52 'topics or body elements.' % self
.name
)
53 document
= self
.state_machine
.document
54 language
= languages
.get_language(document
.settings
.language_code
,
57 title_text
= self
.arguments
[0]
58 text_nodes
, messages
= self
.state
.inline_text(title_text
,
60 title
= nodes
.title(title_text
, '', *text_nodes
)
63 if 'local' in self
.options
:
66 title
= nodes
.title('', language
.labels
['contents'])
67 topic
= nodes
.topic(classes
=['contents'])
68 topic
['classes'] += self
.options
.get('class', [])
69 # the latex2e writer needs source and line for a warning:
70 topic
.source
, topic
.line
= self
.state_machine
.get_source_and_line()
72 if 'local' in self
.options
:
73 topic
['classes'].append('local')
78 name
= language
.labels
['contents']
79 name
= nodes
.fully_normalize_name(name
)
80 if not document
.has_name(name
):
81 topic
['names'].append(name
)
82 document
.note_implicit_target(topic
)
83 pending
= nodes
.pending(parts
.Contents
, rawsource
=self
.block_text
)
84 pending
.details
.update(self
.options
)
85 document
.note_pending(pending
)
87 return [topic
] + messages