def index_role(typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner,
options: Dict = {}, content: List[str] = []
) -> Tuple[List[Node], List[system_message]]:
warnings.warn('index_role() is deprecated. Please use Index class instead.',
RemovedInSphinx40Warning, stacklevel=2)
# create new reference target
env = inliner.document.settings.env
targetid = 'index-%s' % env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
# split text and target in role content
has_explicit_title, title, target = split_explicit_title(text)
title = utils.unescape(title)
target = utils.unescape(target)
# if an explicit target is given, we can process it as a full entry
if has_explicit_title:
entries = process_index_entry(target, targetid)
# otherwise we just create a "single" entry
else:
# but allow giving main entry
main = ''
if target.startswith('!'):
target = target[1:]
title = title[1:]
main = 'main'
entries = [('single', target, targetid, main, None)]
indexnode = addnodes.index()
indexnode['entries'] = entries
set_role_source_info(inliner, lineno, indexnode)
textnode = nodes.Text(title, title)
return [indexnode, targetnode, textnode], []
def __call__(self,
typ,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
env = inliner.document.settings.env
if not typ:
typ = env.temp_data.get('default_role')
if not typ:
typ = env.config.default_role
if not typ:
raise SphinxError('cannot determine default role!')
else:
typ = typ.lower()
if ':' not in typ:
domain, role = '', typ
classes = ['xref', role]
else:
domain, role = typ.split(':', 1)
classes = ['xref', domain, '%s-%s' % (domain, role)]
# if the first character is a bang, don't cross-reference at all
if text[0:1] == '!':
text = utils.unescape(text)[1:]
if self.fix_parens:
text, tgt = self._fix_parens(env, False, text, "")
innernode = self.innernodeclass(rawtext, text, classes=classes)
return self.result_nodes(inliner.document,
env,
innernode,
is_ref=False)
# split title and target in role content
has_explicit_title, title, target = split_explicit_title(text)
title = utils.unescape(title)
target = utils.unescape(target)
# fix-up title and target
if self.lowercase:
target = target.lower()
if self.fix_parens:
title, target = self._fix_parens(env, has_explicit_title, title,
target)
# create the reference node
refnode = self.nodeclass(rawtext,
reftype=role,
refdomain=domain,
refexplicit=has_explicit_title)
# we may need the line number for warnings
set_role_source_info(inliner, lineno, refnode)
title, target = self.process_link(env, refnode, has_explicit_title,
title, target)
# now that the target and title are finally determined, set them
refnode['reftarget'] = target
refnode += self.innernodeclass(rawtext, title, classes=classes)
# we also need the source document
refnode['refdoc'] = env.docname
refnode['refwarn'] = self.warn_dangling
# result_nodes allow further modification of return values
return self.result_nodes(inliner.document, env, refnode, is_ref=True)
def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
# create new reference target
env = inliner.document.settings.env
targetid = 'index-%s' % env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
# split text and target in role content
has_explicit_title, title, target = split_explicit_title(text)
title = utils.unescape(title)
target = utils.unescape(target)
# if an explicit target is given, we can process it as a full entry
if has_explicit_title:
entries = process_index_entry(target, targetid)
# otherwise we just create a "single" entry
else:
# but allow giving main entry
main = ''
if target.startswith('!'):
target = target[1:]
title = title[1:]
main = 'main'
entries = [('single', target, targetid, main)]
indexnode = addnodes.index()
indexnode['entries'] = entries
set_role_source_info(inliner, lineno, indexnode)
textnode = nodes.Text(title, title)
return [indexnode, targetnode, textnode], []
def GrammarProductionRole(typ,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
"""An inline role to declare grammar productions that are not in fact included
in a `productionlist` directive.
Useful to informally introduce a production, as part of running text
"""
#pylint: disable=dangerous-default-value, unused-argument
env = inliner.document.settings.env
targetid = 'grammar-token-{}'.format(text)
target = nodes.target('', '', ids=[targetid])
inliner.document.note_explicit_target(target)
code = nodes.literal(rawtext, text, role=typ.lower())
node = nodes.inline(rawtext,
'',
target,
code,
classes=['inline-grammar-production'])
set_role_source_info(inliner, lineno, node)
env.domaindata['std']['objects']['token', text] = env.docname, targetid
return [node], []
def GrammarProductionRole(typ,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
"""A grammar production not included in a ``productionlist`` directive.
Useful to informally introduce a production, as part of running text.
Example::
:production:`string` indicates a quoted string.
You're not likely to use this role very commonly; instead, use a
`production list
<http://www.sphinx-doc.org/en/stable/markup/para.html#directive-productionlist>`_
and reference its tokens using ``:token:`…```.
"""
#pylint: disable=dangerous-default-value, unused-argument
env = inliner.document.settings.env
targetid = 'grammar-token-{}'.format(text)
target = nodes.target('', '', ids=[targetid])
inliner.document.note_explicit_target(target)
code = nodes.literal(rawtext, text, role=typ.lower())
node = nodes.inline(rawtext,
'',
target,
code,
classes=['inline-grammar-production'])
set_role_source_info(inliner, lineno, node)
env.domaindata['std']['objects']['token', text] = env.docname, targetid
return [node], []
def DocumentRole(typ,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
# type: (unicode, unicode, unicode, int, Inliner, Dict, List[unicode]) -> Tuple[List[nodes.Node], List[nodes.Node]] # NOQA
env = inliner.document.settings.env
# split title and target in role content
has_explicit_title, title, target = split_explicit_title(text)
title = utils.unescape(title)
target = pattern.format(utils.unescape(target))
# create the reference node
refnode = addnodes.pending_xref(rawtext,
reftype='doc',
refdomain='std',
refexplicit=has_explicit_title)
# we may need the line number for warnings
set_role_source_info(inliner, lineno, refnode) # type: ignore
# now that the target and title are finally determined, set them
refnode['reftarget'] = target
refnode += nodes.inline(rawtext, title, classes=['xref', 'doc'])
# we also need the source document
refnode['refdoc'] = env.docname
refnode['refwarn'] = True
return [refnode], []
def index_role(typ, rawtext, text, lineno, inliner, options={}, content=[]):
# create new reference target
env = inliner.document.settings.env
targetid = 'index-%s' % env.new_serialno('index')
targetnode = nodes.target('', '', ids=[targetid])
# split text and target in role content
has_explicit_title, title, target = split_explicit_title(text)
title = utils.unescape(title)
target = utils.unescape(target)
# if an explicit target is given, we can process it as a full entry
if has_explicit_title:
entries = process_index_entry(target, targetid)
# otherwise we just create a "single" entry
else:
# but allow giving main entry
main = ''
if target.startswith('!'):
target = target[1:]
title = title[1:]
main = 'main'
entries = [('single', target, targetid, main)]
indexnode = addnodes.index()
indexnode['entries'] = entries
set_role_source_info(inliner, lineno, indexnode)
textnode = nodes.Text(title, title)
return [indexnode, targetnode, textnode], []
def __call__(self,
name,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
""" Register this document for later building as runnable code file.
Parameters
----------
name : str
The role name used in the document.
rawtext : str
The entire markup snippet, including the role markup.
text : str
The text marked with the role.
lineno : int
The line number where `rawtext` appears in the input.
inliner : object
The inliner instance that called us.
options : dict, optional
Directive options for customization.
content : content, optional
The directive content for customization.
Returns
-------
nodes : list
list of nodes to insert into the document. Can be empty.
messages : list
list of system messages. Can be empty.
"""
# Get objects from context
env = inliner.document.settings.env
# process class options.
# http://docutils.sourceforge.net/docs/howto/rst-roles.html
# Remaining options will be added as attributes of the node (see
# below).
set_classes(options)
# Get title and link
text = utils.unescape(text)
text = self.default_text if text.strip() == '.' else text
has_fname, title, fname = split_explicit_title(text)
if not has_fname:
fname = '/' + env.docname + self.default_extension
refnode = runrole_reference(rawtext,
title,
reftype=self.code_type,
refdoc=env.docname,
reftarget=fname,
**options)
# We may need the line number for warnings
set_role_source_info(inliner, lineno, refnode)
return [refnode], []
def make_checker_chaining(self):
symbol = self.lookup_auto_symbol()
if not symbol:
return
next_checkers = symbol.properties.get('flycheck-next-checkers')
if not next_checkers:
return
title = nodes.title('', 'Chained syntax checkers')
intro = nodes.paragraph()
intro += nodes.Text('The following syntax checkers are ')
chained = addnodes.pending_xref('chained',
reftype='term',
refdomain='std',
reftarget='chaining',
refwarn=True,
refexplicit=True,
reftitle='chaining',
refdoc=self.env.docname)
chained += nodes.emphasis('', 'chained')
intro += chained
intro += nodes.Text(' after this syntax checker:')
checker_list = nodes.enumerated_list()
para = nodes.paragraph()
para += checker_list
outro = nodes.paragraph()
outro += nodes.Text('The ')
outro += nodes.strong('', 'first')
outro += nodes.Text(' suitable syntax checker is used.')
chaining = nodes.admonition(
'',
title,
intro,
para,
outro,
classes=['note', 'el-flycheck-checker-chaining'])
for next_checker in next_checkers:
xref = addnodes.pending_xref(next_checker.checker,
reftype='flyc-checker',
refdomain='el',
refexplicit=False,
reftarget=next_checker.checker,
refwarn=False,
refdoc=self.env.docname)
set_role_source_info(self.state.inliner, self.lineno, xref)
xref += nodes.literal('',
next_checker.checker,
classes=['xref', 'el', 'el-flyc-checker'])
para = nodes.paragraph()
para += xref
if next_checker.warnings_only:
para += nodes.Text(', if there are only warnings')
if next_checker.no_errors:
para += nodes.Text(', if there are no errors')
checker_list += nodes.list_item('', para)
return chaining
def jlreqkasen_role(name,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
"""Role for kasentag."""
text = utils.unescape(text)
node = jlreqkasen(rawtext, base=text, text=text)
set_role_source_info(inliner, lineno, node)
return [node], []
def ruby_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
"""Role for rubytag."""
text = utils.unescape(text)
has_explicit, base, text = split_explicit_title(text)
if not has_explicit:
# the role does not have ruby-text is converted to Text node
node = nodes.Text(text)
else:
node = ruby(rawtext, base=base, text=text)
set_role_source_info(inliner, lineno, node)
return [node], []
def color_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
"""Role for color."""
text = utils.unescape(text)
has_explicit, text, colorspec = split_explicit_title(text)
if not has_explicit:
# the role does not have color-spec is converted to Text node
node = nodes.Text(text)
else:
node = color(rawtext, text, color=colorspec)
set_role_source_info(inliner, lineno, node)
return [node], []
def __call__(self, typ, rawtext, text, lineno, inliner,
options={}, content=[]):
# type: (unicode, unicode, unicode, int, Inliner, Dict, List[unicode]) -> Tuple[List[nodes.Node], List[nodes.Node]] # NOQA
env = inliner.document.settings.env
if not typ:
typ = env.temp_data.get('default_role')
if not typ:
typ = env.config.default_role
if not typ:
raise SphinxError('cannot determine default role!')
else:
typ = typ.lower()
if ':' not in typ:
domain, role = '', typ # type: unicode, unicode
classes = ['xref', role]
else:
domain, role = typ.split(':', 1)
classes = ['xref', domain, '%s-%s' % (domain, role)]
# if the first character is a bang, don't cross-reference at all
if text[0:1] == '!':
text = utils.unescape(text)[1:]
if self.fix_parens:
text, tgt = self._fix_parens(env, False, text, "")
innernode = self.innernodeclass(rawtext, text, classes=classes)
return self.result_nodes(inliner.document, env, innernode,
is_ref=False)
# split title and target in role content
has_explicit_title, title, target = split_explicit_title(text)
title = utils.unescape(title)
target = utils.unescape(target)
# fix-up title and target
if self.lowercase:
target = target.lower()
if self.fix_parens:
title, target = self._fix_parens(
env, has_explicit_title, title, target)
# create the reference node
refnode = self.nodeclass(rawtext, reftype=role, refdomain=domain,
refexplicit=has_explicit_title)
# we may need the line number for warnings
set_role_source_info(inliner, lineno, refnode) # type: ignore
title, target = self.process_link(
env, refnode, has_explicit_title, title, target)
# now that the target and title are finally determined, set them
refnode['reftarget'] = target
refnode += self.innernodeclass(rawtext, title, classes=classes)
# we also need the source document
refnode['refdoc'] = env.docname
refnode['refwarn'] = self.warn_dangling
# result_nodes allow further modification of return values
return self.result_nodes(inliner.document, env, refnode, is_ref=True)
def GrammarProductionRole(typ, rawtext, text, lineno, inliner, options={}, content=[]):
"""An inline role to declare grammar productions that are not in fact included
in a `productionlist` directive.
Useful to informally introduce a production, as part of running text
"""
#pylint: disable=dangerous-default-value, unused-argument
env = inliner.document.settings.env
targetid = 'grammar-token-{}'.format(text)
target = nodes.target('', '', ids=[targetid])
inliner.document.note_explicit_target(target)
code = nodes.literal(rawtext, text, role=typ.lower())
node = nodes.inline(rawtext, '', target, code, classes=['inline-grammar-production'])
set_role_source_info(inliner, lineno, node)
env.domaindata['std']['objects']['token', text] = env.docname, targetid
return [node], []
def make_checker_chaining(self):
symbol = self.lookup_auto_symbol()
if not symbol:
return
next_checkers = symbol.properties.get('flycheck-next-checkers')
if not next_checkers:
return
title = nodes.title('', 'Chained syntax checkers')
intro = nodes.paragraph()
intro += nodes.Text('The following syntax checkers are ')
chained = addnodes.pending_xref(
'chained', reftype='term', refdomain='std', reftarget='chaining',
refwarn=True, refexplicit=True, reftitle='chaining',
refdoc=self.env.docname)
chained += nodes.emphasis('', 'chained')
intro += chained
intro += nodes.Text(' after this syntax checker:')
checker_list = nodes.enumerated_list()
para = nodes.paragraph()
para += checker_list
outro = nodes.paragraph()
outro += nodes.Text('The ')
outro += nodes.strong('', 'first')
outro += nodes.Text(' suitable syntax checker is used.')
chaining = nodes.admonition(
'', title, intro, para, outro,
classes=['note', 'el-flycheck-checker-chaining'])
for next_checker in next_checkers:
xref = addnodes.pending_xref(
next_checker.checker,
reftype='flyc-checker', refdomain='el',
refexplicit=False, reftarget=next_checker.checker,
refwarn=False, refdoc=self.env.docname)
set_role_source_info(self.state.inliner, self.lineno, xref)
xref += nodes.literal('', next_checker.checker,
classes=['xref', 'el', 'el-flyc-checker'])
para = nodes.paragraph()
para += xref
if next_checker.warnings_only:
para += nodes.Text(', if there are only warnings')
if next_checker.no_errors:
para += nodes.Text(', if there are no errors')
checker_list += nodes.list_item('', para)
return chaining
def run(self):
has_fname, text, fname = split_explicit_title(self.text)
if has_fname:
raise ExtensionError('Page role cannot have explicit title')
nb_url = f'{UCB_NC_NB_URL}/{text}.ipynb'
license_url = f'{self.env.config.html_baseurl}/license'
node = nodes.note(
text,
nodes.paragraph(
text, '', nodes.Text('This page has content from the '),
nodes.reference(nb_url, text, refuri=nb_url),
nodes.Text(' notebook of an older version of the '),
nodes.reference(UCB_URL,
'UC Berkeley data science course',
refuri=UCB_URL),
nodes.Text('. See the Berkeley course section of the '),
nodes.reference(license_url,
'license file',
refuri=license_url), nodes.Text('.')))
set_role_source_info(self.inliner, self.lineno, node)
return [node], []
def macro_def_role(name,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
app = inliner.document.settings.env.app
docname = inliner.document.settings.env.docname
# Create a new linkable target using the macro name
targetid = text
targetnode = nodes.target('', text, ids=[targetid], classes=["macro-def"])
# Automatically include an index entry for macro definitions
entries = process_index_entry(text, targetid)
indexnode = addnodes.index()
indexnode['entries'] = entries
set_role_source_info(inliner, lineno, indexnode)
return [indexnode, targetnode], []
def make_variable_properties(self):
"""Get a node for the variable properties.
Look at all special properties of the documented variables, and create
an admonition that describes all these properties in a human-readable
way.
Return the admonition node, or ``None``, if the documented variable has
no special properties.
"""
title = corenodes.title('Variable properties', 'Variable properties')
body = corenodes.paragraph('', '')
props = corenodes.admonition(
'', title, body, classes=['note', 'el-variable-properties'])
if self.is_local_variable:
body += corenodes.Text(
'Automatically becomes buffer-local when set. ')
if self.is_risky_variable:
body += corenodes.Text(
'This variable may be risky if used as a file-local '
'variable. ')
safe_predicate = self.get_safe_variable_predicate()
if safe_predicate:
body += corenodes.Text(
'This variable is safe as a file local variable if its value '
'satisfies the predicate ')
if SYMBOL_PATTERN.match(safe_predicate):
xref = addnodes.pending_xref(
safe_predicate, reftype='function', refdomain='el',
refexplicit=False, reftarget=safe_predicate,
refwarn=False, refdoc=self.env.docname)
set_role_source_info(self.state.inliner, self.lineno, xref)
xref += corenodes.literal(safe_predicate, safe_predicate,
classes=['xref', 'el', 'el-function'])
body += xref
else:
body += corenodes.literal(safe_predicate, safe_predicate)
body += corenodes.Text('. ')
return props if len(body) > 0 else None
def classad_attribute_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
app = inliner.document.settings.env.app
docname = inliner.document.settings.env.docname
# Create the attribute title with the classad attribute name, also containing an anchor
anchor_title_node = make_anchor_title_node(text)
# Create a headerlink node, which can be used to link to the anchor
headerlink_node = make_headerlink_node(str(text), options)
# Determine the classad type (job, submitted, collector, etc.) by ripping it out of the document title
attr_type = ""
type_matches = re.findall(r"/([\w]*)-classad-attributes", docname)
for match in type_matches:
attr_type = match.capitalize() + " "
# Automatically include an index entry
entries = process_index_entry(f"{text} ({attr_type}ClassAd Attribute)", text)
index_node = addnodes.index()
index_node['entries'] = entries
set_role_source_info(inliner, lineno, index_node)
return [index_node, anchor_title_node, headerlink_node], []
def GrammarProductionRole(typ, rawtext, text, lineno, inliner, options={}, content=[]):
"""A grammar production not included in a ``productionlist`` directive.
Useful to informally introduce a production, as part of running text.
Example::
:production:`string` indicates a quoted string.
You're not likely to use this role very commonly; instead, use a
`production list
<http://www.sphinx-doc.org/en/stable/markup/para.html#directive-productionlist>`_
and reference its tokens using ``:token:`…```.
"""
#pylint: disable=dangerous-default-value, unused-argument
env = inliner.document.settings.env
targetid = 'grammar-token-{}'.format(text)
target = nodes.target('', '', ids=[targetid])
inliner.document.note_explicit_target(target)
code = nodes.literal(rawtext, text, role=typ.lower())
node = nodes.inline(rawtext, '', target, code, classes=['inline-grammar-production'])
set_role_source_info(inliner, lineno, node)
env.domaindata['std']['objects']['token', text] = env.docname, targetid
return [node], []
def deleted_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
"""Role for del."""
text = utils.unescape(text)
node = deleted(rawtext, text)
set_role_source_info(inliner, lineno, node)
return [node], []
