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 __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 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 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], []