def run_role(self, name,
options=None,
content=None):
"""Generate a role node.
options : dict
key value arguments.
content : content
content of the directive
Returns
-------
node : docutil Node
Node generated by the arguments.
"""
if options is None:
options = {}
if content is None:
content = []
role_fn, msg = role(name,
self.language,
self.node.line,
self.reporter)
# add decode from utf-8
content = content.encode('utf-8')
content = content.decode('utf-8')
vec, msg = role_fn(name,
rawtext=content,
text=content,
lineno=self.node.line,
inliner=self.memo.inliner,
options=options,
content=content)
assert len(vec) == 1, 'only support one list in role'
return vec[0]
def run_role(self, name,
options={},
content=[]):
"""Generate a role node.
options : dict
key value arguments.
content : content
content of the directive
Returns
-------
node : docutil Node
Node generated by the arguments.
"""
role_fn, msg = role(name,
self.language,
self.node.line,
self.reporter)
vec, msg= role_fn(name,
rawtext=str(content),
text=str(content),
lineno=self.node.line,
inliner=self.memo.inliner,
options=options,
content=content)
assert len(vec) == 1, 'only support one list in role'
return vec[0]
def run_role(self, name,
options=None,
content=None):
"""Generate a role node.
options : dict
key value arguments.
content : content
content of the directive
Returns
-------
node : docutil Node
Node generated by the arguments.
"""
if options is None:
options = {}
if content is None:
content = []
role_fn, msg = role(name,
self.language,
self.node.line,
self.reporter)
vec, msg = role_fn(name,
rawtext=str(content),
text=str(content),
lineno=self.node.line,
inliner=self.memo.inliner,
options=options,
content=content)
assert len(vec) == 1, 'only support one list in role'
return vec[0]
def render_role(self, token):
content = token.children[0].content
name = token.role_name
# TODO role name white/black lists
try:
lineno = token.position.line_start
except (AttributeError, TypeError):
lineno = 0
inliner = MockInliner(self, lineno)
role_func, messages = roles.role(
name, self.language_module, lineno, self.reporter
)
rawsource = ":{}:`{}`".format(name, content)
# # backslash escapes converted to nulls (``\x00``)
text = span_tokens.EscapeSequence.strip(content)
if role_func:
nodes, messages2 = role_func(name, rawsource, text, lineno, inliner)
# return nodes, messages + messages2
self.current_node += nodes
else:
message = self.reporter.error(
'Unknown interpreted text role "{}".'.format(name), line=lineno
)
# return ([self.problematic(content, content, msg)], messages + [msg])
problematic = inliner.problematic(text, rawsource, message)
self.current_node += problematic
def catchall_interpreted(self, rawsource, text, role, lineno):
"""Interpreted text role dispatch method.
Replacement for Inliner.interpreted(): if a role is not known, build one
on the fly instead of reporting an error.
"""
role_fn, messages = roles.role(role, self.language, lineno, self.reporter)
# in case it's missing, register a generic role
if not role_fn:
role_obj = AnyRole(role)
roles.register_canonical_role(role, role_obj)
role_fn, messages = roles.role(role, self.language, lineno,
self.reporter)
assert role_fn, "can't find just defined role"
nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
return nodes, messages + messages2
def catchall_interpreted(self, rawsource, text, role, lineno):
"""Interpreted text role dispatch method.
Replacement for Inliner.interpreted(): if a role is not known, build one
on the fly instead of reporting an error.
"""
role_fn, messages = roles.role(role, self.language, lineno,
self.reporter)
# in case it's missing, register a generic role
if not role_fn:
role_obj = AnyRole(role)
roles.register_canonical_role(role, role_obj)
role_fn, messages = roles.role(
role, self.language, lineno, self.reporter)
assert role_fn, "can't find just defined role"
nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
return nodes, messages + messages2
def run(self):
"""Dynamically create and register a custom interpreted text role."""
if self.content_offset > self.lineno or not self.content:
raise self.error('"%s" directive requires arguments on the first '
'line.' % self.name)
args = self.content[0]
match = self.argument_pattern.match(args)
if not match:
raise self.error('"%s" directive arguments not valid role names: '
'"%s".' % (self.name, args))
new_role_name = match.group(1)
base_role_name = match.group(3)
messages = []
if base_role_name:
base_role, messages = roles.role(base_role_name,
self.state_machine.language,
self.lineno, self.state.reporter)
if base_role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % base_role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
else:
base_role = roles.generic_custom_role
assert not hasattr(base_role, 'arguments'), (
'Supplemental directive arguments for "%s" directive not '
'supported (specified by "%r" role).' % (self.name, base_role))
try:
converted_role = convert_directive_function(base_role)
(arguments, options, content,
content_offset) = (self.state.parse_directive_block(
self.content[1:],
self.content_offset,
converted_role,
option_presets={}))
except states.MarkupError as detail:
error = self.state_machine.reporter.error(
'Error in "%s" directive:\n%s.' % (self.name, detail),
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
if 'class' not in options:
try:
options['class'] = directives.class_option(new_role_name)
except ValueError as detail:
error = self.state_machine.reporter.error(
'Invalid argument for "%s" directive:\n%s.' %
(self.name, SafeString(detail)),
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
role = roles.CustomRole(new_role_name, base_role, options, content)
roles.register_local_role(new_role_name, role)
return messages
def default_role(docname: str, name: str) -> Generator[None, None, None]:
if name:
dummy_reporter = Reporter('', 4, 4)
role_fn, _ = roles.role(name, english, 0, dummy_reporter)
if role_fn:
docutils.register_role('', role_fn)
else:
logger.warning(__('default role %s not found'), name, location=docname)
yield
docutils.unregister_role('')
def run(self):
"""Dynamically create and register a custom interpreted text role."""
if self.content_offset > self.lineno or not self.content:
raise self.error('"%s" directive requires arguments on the first '
'line.' % self.name)
args = self.content[0]
match = self.argument_pattern.match(args)
if not match:
raise self.error('"%s" directive arguments not valid role names: '
'"%s".' % (self.name, args))
new_role_name = match.group(1)
base_role_name = match.group(3)
messages = []
if base_role_name:
base_role, messages = roles.role(
base_role_name, self.state_machine.language, self.lineno,
self.state.reporter)
if base_role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % base_role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
else:
base_role = roles.generic_custom_role
assert not hasattr(base_role, 'arguments'), (
'Supplemental directive arguments for "%s" directive not '
'supported (specified by "%r" role).' % (self.name, base_role))
try:
converted_role = convert_directive_function(base_role)
(arguments, options, content, content_offset) = (
self.state.parse_directive_block(
self.content[1:], self.content_offset, converted_role,
option_presets={}))
except states.MarkupError as detail:
error = self.state_machine.reporter.error(
'Error in "%s" directive:\n%s.' % (self.name, detail),
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
if 'class' not in options:
try:
options['class'] = directives.class_option(new_role_name)
except ValueError as detail:
error = self.state_machine.reporter.error(
'Invalid argument for "%s" directive:\n%s.'
% (self.name, SafeString(detail)), nodes.literal_block(
self.block_text, self.block_text), line=self.lineno)
return messages + [error]
role = roles.CustomRole(new_role_name, base_role, options, content)
roles.register_local_role(new_role_name, role)
return messages
def default_role(docname, name):
# type: (unicode, unicode) -> Generator
if name:
dummy_reporter = Reporter('', 4, 4)
role_fn, _ = roles.role(name, english, 0, dummy_reporter)
if role_fn:
roles._roles[''] = role_fn
else:
logger.warning('default role %s not found', name, location=docname)
yield
roles._roles.pop('', None) # if a document has set a local default role
def default_role(docname, name):
# type: (unicode, unicode) -> Generator
if name:
dummy_reporter = Reporter('', 4, 4)
role_fn, _ = roles.role(name, english, 0, dummy_reporter)
if role_fn:
roles._roles[''] = role_fn
else:
logger.warning(__('default role %s not found'), name, location=docname)
yield
roles._roles.pop('', None) # if a document has set a local default role
def role(name, arguments, options, content, lineno, content_offset, block_text,
state, state_machine):
"""Dynamically create and register a custom interpreted text role."""
if content_offset > lineno or not content:
error = state_machine.reporter.error(
'"%s" directive requires arguments on the first line.' % name,
nodes.literal_block(block_text, block_text),
line=lineno)
return [error]
args = content[0]
match = role_arg_pat.match(args)
if not match:
error = state_machine.reporter.error(
'"%s" directive arguments not valid role names: "%s".' %
(name, args),
nodes.literal_block(block_text, block_text),
line=lineno)
return [error]
new_role_name = match.group(1)
base_role_name = match.group(3)
messages = []
if base_role_name:
base_role, messages = roles.role(base_role_name,
state_machine.language, lineno,
state.reporter)
if base_role is None:
error = state.reporter.error(
'Unknown interpreted text role "%s".' % base_role_name,
nodes.literal_block(block_text, block_text),
line=lineno)
return messages + [error]
else:
base_role = roles.generic_custom_role
assert not hasattr(base_role, 'arguments'), (
'Supplemental directive arguments for "%s" directive not supported'
'(specified by "%r" role).' % (name, base_role))
try:
(arguments, options, content,
content_offset) = (state.parse_directive_block(content[1:],
content_offset,
base_role,
option_presets={}))
except states.MarkupError, detail:
error = state_machine.reporter.error(
'Error in "%s" directive:\n%s.' % (name, detail),
nodes.literal_block(block_text, block_text),
line=lineno)
return messages + [error]
def run(self):
if not self.arguments:
if '' in roles._roles:
# restore the "default" default role
del roles._roles['']
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
roles._roles[''] = role
return messages
def role(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine):
"""Dynamically create and register a custom interpreted text role."""
if content_offset > lineno or not content:
error = state_machine.reporter.error(
'"%s" directive requires arguments on the first line.' % name,
nodes.literal_block(block_text, block_text),
line=lineno,
)
return [error]
args = content[0]
match = role_arg_pat.match(args)
if not match:
error = state_machine.reporter.error(
'"%s" directive arguments not valid role names: "%s".' % (name, args),
nodes.literal_block(block_text, block_text),
line=lineno,
)
return [error]
new_role_name = match.group(1)
base_role_name = match.group(3)
messages = []
if base_role_name:
base_role, messages = roles.role(base_role_name, state_machine.language, lineno, state.reporter)
if base_role is None:
error = state.reporter.error(
'Unknown interpreted text role "%s".' % base_role_name,
nodes.literal_block(block_text, block_text),
line=lineno,
)
return messages + [error]
else:
base_role = roles.generic_custom_role
assert not hasattr(base_role, "arguments"), (
'Supplemental directive arguments for "%s" directive not supported'
'(specified by "%r" role).' % (name, base_role)
)
try:
(arguments, options, content, content_offset) = state.parse_directive_block(
content[1:], content_offset, base_role, option_presets={}
)
except states.MarkupError, detail:
error = state_machine.reporter.error(
'Error in "%s" directive:\n%s.' % (name, detail), nodes.literal_block(block_text, block_text), line=lineno
)
return messages + [error]
def run(self):
if not self.arguments:
if roles._roles.has_key(''):
# restore the "default" default role
del roles._roles['']
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
roles._roles[''] = role
# @@@ should this be local to the document, not the parser?
return messages
def run(self):
if not self.arguments:
if '' in roles._roles:
# restore the "default" default role
del roles._roles['']
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
roles._roles[''] = role
# @@@ should this be local to the document, not the parser?
return messages
def run(self) -> List[Node]:
if not self.arguments:
docutils.unregister_role('')
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role:
docutils.register_role('', role)
self.env.temp_data['default_role'] = role_name
else:
literal_block = nodes.literal_block(self.block_text, self.block_text)
reporter = self.state.reporter
error = reporter.error('Unknown interpreted text role "%s".' % role_name,
literal_block, line=self.lineno)
messages += [error]
return cast(List[nodes.Node], messages)
def run(self):
if not self.arguments:
if '' in roles._roles:
# restore the "default" default role
del roles._roles['']
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
roles._roles[''] = role
self.state.document.settings.env.temp_data['default_role'] = role_name
return messages
def run(self):
# type: () -> List[nodes.Node]
if not self.arguments:
if '' in roles._roles:
# restore the "default" default role
del roles._roles['']
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role is None:
error = self.state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(self.block_text, self.block_text),
line=self.lineno)
return messages + [error]
roles._roles[''] = role
self.state.document.settings.env.temp_data['default_role'] = role_name
return messages
def default_role(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""Set the default interpreted text role."""
if not arguments:
if roles._roles.has_key(''):
# restore the "default" default role
del roles._roles['']
return []
role_name = arguments[0]
role, messages = roles.role(
role_name, state_machine.language, lineno, state.reporter)
if role is None:
error = state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(block_text, block_text), line=lineno)
return messages + [error]
roles._roles[''] = role
# @@@ should this be local to the document, not the parser?
return messages
def run(self):
# type: () -> List[nodes.Node]
if not self.arguments:
docutils.unregister_role('')
return []
role_name = self.arguments[0]
role, messages = roles.role(role_name, self.state_machine.language,
self.lineno, self.state.reporter)
if role:
docutils.register_role('', role)
self.env.temp_data['default_role'] = role_name
else:
literal_block = nodes.literal_block(self.block_text, self.block_text)
reporter = self.state.reporter
error = reporter.error('Unknown interpreted text role "%s".' % role_name,
literal_block, line=self.lineno)
messages += [error]
return cast(List[nodes.Node], messages)
def default_role(name, arguments, options, content, lineno,
content_offset, block_text, state, state_machine):
"""Set the default interpreted text role."""
if not arguments:
if roles._roles.has_key(''):
# restore the "default" default role
del roles._roles['']
return []
role_name = arguments[0]
role, messages = roles.role(
role_name, state_machine.language, lineno, state.reporter)
if role is None:
error = state.reporter.error(
'Unknown interpreted text role "%s".' % role_name,
nodes.literal_block(block_text, block_text), line=lineno)
return messages + [error]
roles._roles[''] = role
# @@@ should this be local to the document, not the parser?
return messages
def render_myst_role(self, token):
name = token.meta["name"]
text = token.content
rawsource = f":{name}:`{token.content}`"
lineno = token.map[0] if token.map else 0
role_func, messages = roles.role(name, self.language_module, lineno,
self.reporter)
inliner = MockInliner(self, lineno)
if role_func:
nodes, messages2 = role_func(name, rawsource, text, lineno,
inliner)
# return nodes, messages + messages2
self.current_node += nodes
else:
message = self.reporter.error(
'Unknown interpreted text role "{}".'.format(name),
line=lineno)
problematic = inliner.problematic(text, rawsource, message)
self.current_node += problematic
def interpreted(
self, rawsource: str, text: str, role: str, lineno: int
) -> Tuple[List[nodes.Node], List[nodes.system_message]]:
"""Handle an interpreted text role, e.g. :role:interpreted` or `interpreted`:role:
The role function is located and returned, then used to create the requisite
nodes and messages.
"""
role_fn, messages = roles.role(role, self.language, lineno, self.reporter)
if role_fn:
nodes, messages2 = role_fn(role, rawsource, text, lineno, self)
try:
nodes[0][0].rawsource = unescape(text, True)
except IndexError:
pass
return nodes, messages + messages2
else:
msg = self.reporter.error(
'Unknown interpreted text role "%s".' % role, line=lineno
)
return ([self.problematic(rawsource, rawsource, msg)], messages + [msg])
def read_doc(self, docname, app=None):
# type: (unicode, Sphinx) -> None
"""Parse a file and add/update inventory entries for the doctree."""
self.temp_data['docname'] = docname
# defaults to the global default, but can be re-set in a document
self.temp_data['default_domain'] = \
self.domains.get(self.config.primary_domain)
self.settings['input_encoding'] = self.config.source_encoding
self.settings['trim_footnote_reference_space'] = \
self.config.trim_footnote_reference_space
self.settings['gettext_compact'] = self.config.gettext_compact
docutilsconf = path.join(self.srcdir, 'docutils.conf')
# read docutils.conf from source dir, not from current dir
OptionParser.standard_config_files[1] = docutilsconf
if path.isfile(docutilsconf):
self.note_dependency(docutilsconf)
with sphinx_domains(self):
if self.config.default_role:
role_fn, messages = roles.role(self.config.default_role, english,
0, dummy_reporter)
if role_fn:
roles._roles[''] = role_fn
else:
logger.warning('default role %s not found', self.config.default_role,
location=docname)
codecs.register_error('sphinx', self.warn_and_replace) # type: ignore
# publish manually
reader = SphinxStandaloneReader(self.app, parsers=self.config.source_parsers)
pub = Publisher(reader=reader,
writer=SphinxDummyWriter(),
destination_class=NullOutput)
pub.set_components(None, 'restructuredtext', None)
pub.process_programmatic_settings(None, self.settings, None)
src_path = self.doc2path(docname)
source = SphinxFileInput(app, self, source=None, source_path=src_path,
encoding=self.config.source_encoding)
pub.source = source
pub.settings._source = src_path
pub.set_destination(None, None)
pub.publish()
doctree = pub.document
# post-processing
for domain in itervalues(self.domains):
domain.process_doc(self, docname, doctree)
# allow extension-specific post-processing
if app:
app.emit('doctree-read', doctree)
# store time of reading, for outdated files detection
# (Some filesystems have coarse timestamp resolution;
# therefore time.time() can be older than filesystem's timestamp.
# For example, FAT32 has 2sec timestamp resolution.)
self.all_docs[docname] = max(
time.time(), path.getmtime(self.doc2path(docname)))
if self.versioning_condition:
old_doctree = None
if self.versioning_compare:
# get old doctree
try:
with open(self.doc2path(docname,
self.doctreedir, '.doctree'), 'rb') as f:
old_doctree = pickle.load(f)
except EnvironmentError:
pass
# add uids for versioning
if not self.versioning_compare or old_doctree is None:
list(add_uids(doctree, self.versioning_condition))
else:
list(merge_doctrees(
old_doctree, doctree, self.versioning_condition))
# make it picklable
doctree.reporter = None
doctree.transformer = None
doctree.settings.warning_stream = None
doctree.settings.env = None
doctree.settings.record_dependencies = None
# cleanup
self.temp_data.clear()
self.ref_context.clear()
roles._roles.pop('', None) # if a document has set a local default role
# save the parsed doctree
doctree_filename = self.doc2path(docname, self.doctreedir,
'.doctree')
ensuredir(path.dirname(doctree_filename))
with open(doctree_filename, 'wb') as f:
pickle.dump(doctree, f, pickle.HIGHEST_PROTOCOL)
