我们从Python开源项目中，提取了以下16个代码示例，用于说明如何使用sphinx.addnodes.pending_xref()。
def build_reference_node(self, fromdocname, builder, docname, labelid, sectname, rolename, **options): nodeclass = options.pop('nodeclass', nodes.reference) newnode = nodeclass('', '', internal=True, **options) innernode = nodes.inline(sectname, sectname) if innernode.get('classes') is not None: innernode['classes'].append('std') innernode['classes'].append('std-' + rolename) if docname == fromdocname: newnode['refid'] = labelid else: # set more info in contnode; in case the # get_relative_uri call raises NoUri, # the builder will then have to resolve these contnode = addnodes.pending_xref('') contnode['refdocname'] = docname contnode['refsectname'] = sectname newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) if labelid: newnode['refuri'] += '#' + labelid newnode.append(innernode) return newnode
def describe_signature(self, signode, mode, env, prefix, parentScope): _verify_description_mode(mode) if mode == 'markType': targetText = prefix + text_type(self) pnode = addnodes.pending_xref( '', refdomain='cpp', reftype='type', reftarget=targetText, modname=None, classname=None) pnode['cpp:parent'] = [parentScope] pnode += nodes.Text(text_type(self.identifier)) signode += pnode elif mode == 'lastIsName': name = text_type(self.identifier) signode += addnodes.desc_name(name, name) else: raise Exception('Unknown description mode: %s' % mode) if self.templateArgs: signode += nodes.Text('<') first = True for a in self.templateArgs: if not first: signode += nodes.Text(', ') first = False a.describe_signature(signode, 'markType', env, parentScope=parentScope) signode += nodes.Text('>')
def build_reference_node(self, fromdocname, builder, docname, labelid, sectname, **options): nodeclass = options.pop('nodeclass', nodes.reference) newnode = nodeclass('', '', internal=True, **options) innernode = nodes.inline(sectname, sectname) if docname == fromdocname: newnode['refid'] = labelid else: # set more info in contnode; in case the # get_relative_uri call raises NoUri, # the builder will then have to resolve these contnode = addnodes.pending_xref('') contnode['refdocname'] = docname contnode['refsectname'] = sectname newnode['refuri'] = builder.get_relative_uri( fromdocname, docname) if labelid: newnode['refuri'] += '#' + labelid newnode.append(innernode) return newnode
def apply(self): config = self.document.settings.env.config github_project = config.github_project issue_pattern = config.github_issue_pattern if isinstance(issue_pattern, str_t): issue_pattern = re.compile(issue_pattern) for node in self.document.traverse(nodes.Text): parent = node.parent if isinstance(parent, (nodes.literal, nodes.FixedTextElement)): continue text = text_t(node) new_nodes = [] last_issue_ref_end = 0 for match in issue_pattern.finditer(text): head = text[last_issue_ref_end:match.start()] if head: new_nodes.append(nodes.Text(head)) last_issue_ref_end = match.end() issuetext = match.group(0) issue_id = match.group(1) refnode = pending_xref() refnode['reftarget'] = issue_id refnode['reftype'] = 'issue' refnode['github_project'] = github_project reftitle = issuetext refnode.append(nodes.inline( issuetext, reftitle, classes=['xref', 'issue'])) new_nodes.append(refnode) if not new_nodes: continue tail = text[last_issue_ref_end:] if tail: new_nodes.append(nodes.Text(tail)) parent.replace(node, new_nodes)
def token_xrefs(text): retnodes = [] pos = 0 for m in token_re.finditer(text): if m.start() > pos: txt = text[pos:m.start()] retnodes.append(nodes.Text(txt, txt)) refnode = addnodes.pending_xref( m.group(1), reftype='token', refdomain='std', reftarget=m.group(1)) refnode += nodes.literal(m.group(1), m.group(1), classes=['xref']) retnodes.append(refnode) pos = m.end() if pos < len(text): retnodes.append(nodes.Text(text[pos:], text[pos:])) return retnodes
def apply(self): for citnode in self.document.traverse(nodes.citation_reference): cittext = citnode.astext() refnode = addnodes.pending_xref(cittext, reftype='citation', reftarget=cittext, refwarn=True, ids=citnode["ids"]) refnode.source = citnode.source or citnode.parent.source refnode.line = citnode.line or citnode.parent.line refnode += nodes.Text('[' + cittext + ']') citnode.parent.replace(citnode, refnode)
def _parse_type(self, node, ctype): # add cross-ref nodes for all words for part in [_f for _f in wsplit_re.split(ctype) if _f]: tnode = nodes.Text(part, part) if part[0] in string.ascii_letters+'_' and \ part not in self.stopwords: pnode = addnodes.pending_xref( '', refdomain='c', reftype='type', reftarget=part, modname=None, classname=None) pnode += tnode node += pnode else: node += tnode
def write(self, *ignored): docwriter = ManualPageWriter(self) docsettings = OptionParser( defaults=self.env.settings, components=(docwriter,), read_config_files=True).get_default_values() self.info(bold('writing... '), nonl=True) for info in self.config.man_pages: docname, name, description, authors, section = info if isinstance(authors, string_types): if authors: authors = [authors] else: authors = [] targetname = '%s.%s' % (name, section) self.info(darkgreen(targetname) + ' { ', nonl=True) destination = FileOutput( destination_path=path.join(self.outdir, targetname), encoding='utf-8') tree = self.env.get_doctree(docname) docnames = set() largetree = inline_all_toctrees(self, docnames, docname, tree, darkgreen, [docname]) self.info('} ', nonl=True) self.env.resolve_references(largetree, docname, self) # remove pending_xref nodes for pendingnode in largetree.traverse(addnodes.pending_xref): pendingnode.replace_self(pendingnode.children) largetree.settings = docsettings largetree.settings.title = name largetree.settings.subtitle = description largetree.settings.authors = authors largetree.settings.section = section docwriter.write(largetree, destination) self.info()
def assemble_doctree(self, indexfile, toctree_only, appendices): self.docnames = set([indexfile] + appendices) self.info(darkgreen(indexfile) + " ", nonl=1) tree = self.env.get_doctree(indexfile) tree['docname'] = indexfile if toctree_only: # extract toctree nodes from the tree and put them in a # fresh document new_tree = new_document('<texinfo output>') new_sect = nodes.section() new_sect += nodes.title(u'<Set title in conf.py>', u'<Set title in conf.py>') new_tree += new_sect for node in tree.traverse(addnodes.toctree): new_sect += node tree = new_tree largetree = inline_all_toctrees(self, self.docnames, indexfile, tree, darkgreen, [indexfile]) largetree['docname'] = indexfile for docname in appendices: appendix = self.env.get_doctree(docname) appendix['docname'] = docname largetree.append(appendix) self.info() self.info("resolving references...") self.env.resolve_references(largetree, indexfile, self) # TODO: add support for external :ref:s for pendingnode in largetree.traverse(addnodes.pending_xref): docname = pendingnode['refdocname'] sectname = pendingnode['refsectname'] newnodes = [nodes.emphasis(sectname, sectname)] for subdir, title in self.titles: if docname.startswith(subdir): newnodes.append(nodes.Text(_(' (in '), _(' (in '))) newnodes.append(nodes.emphasis(title, title)) newnodes.append(nodes.Text(')', ')')) break else: pass pendingnode.replace_self(newnodes) return largetree
def visitHole(self, ctx:TacticNotationsParser.HoleContext): hole = ctx.ID().getText() token_name = hole[1:] node = nodes.inline(hole, token_name, classes=["hole"]) return [addnodes.pending_xref(token_name, node, reftype='token', refdomain='std', reftarget=token_name)]
def apply(self, **kwargs): for ref in self.document.traverse(nodes.reference): # Skip inter-document links if 'refname' in ref: if self.document.nameids.get(ref['refname']): continue # Convert remaining non-external links to intra-document references refuri = ref['refuri'] if 'refuri' in ref else None if not refuri or not '://' in refuri: # Get the raw text (strip ``s and _) rawtext = re.sub('^`(.*)`_?$', '\\1', ref.rawsource) # Create xref node xref = addnodes.pending_xref( rawtext, reftype='ref', refdomain='std', refexplicit=(refuri is not None)) # Rewrite section links if not refuri: refuri = ref['name'] # Fill target information xref['reftarget'] = refuri.lower() xref['refwarn'] = True xref['refdoc'] = self.document.settings.env.docname # Add ref text xref += nodes.inline(rawtext, ref['name'], classes=ref['classes']) # Replace the old node ref.replace_self(xref) #==============================================================================
def process_refonly_bullet_lists(self, docname, doctree): """Change refonly bullet lists to use compact_paragraphs. Specifically implemented for 'Indices and Tables' section, which looks odd when html_compact_lists is false. """ if self.config.html_compact_lists: return class RefOnlyListChecker(nodes.GenericNodeVisitor): """Raise `nodes.NodeFound` if non-simple list item is encountered. Here 'simple' means a list item containing only a paragraph with a single reference in it. """ def default_visit(self, node): raise nodes.NodeFound def visit_bullet_list(self, node): pass def visit_list_item(self, node): children = [] for child in node.children: if not isinstance(child, nodes.Invisible): children.append(child) if len(children) != 1: raise nodes.NodeFound if not isinstance(children[0], nodes.paragraph): raise nodes.NodeFound para = children[0] if len(para) != 1: raise nodes.NodeFound if not isinstance(para[0], addnodes.pending_xref): raise nodes.NodeFound raise nodes.SkipChildren def invisible_visit(self, node): """Invisible nodes should be ignored.""" pass def check_refonly_list(node): """Check for list with only references in it.""" visitor = RefOnlyListChecker(doctree) try: node.walk(visitor) except nodes.NodeFound: return False else: return True for node in doctree.traverse(nodes.bullet_list): if check_refonly_list(node): for item in node.traverse(nodes.list_item): para = item[0] ref = para[0] compact_para = addnodes.compact_paragraph() compact_para += ref item.replace(para, compact_para)
def resolve_references(self, doctree, fromdocname, builder): for node in doctree.traverse(addnodes.pending_xref): contnode = node[0].deepcopy() newnode = None typ = node['reftype'] target = node['reftarget'] refdoc = node.get('refdoc', fromdocname) domain = None try: if 'refdomain' in node and node['refdomain']: # let the domain try to resolve the reference try: domain = self.domains[node['refdomain']] except KeyError: raise NoUri newnode = domain.resolve_xref(self, refdoc, builder, typ, target, node, contnode) # really hardwired reference types elif typ == 'any': newnode = self._resolve_any_reference(builder, node, contnode) elif typ == 'doc': newnode = self._resolve_doc_reference(builder, node, contnode) elif typ == 'citation': newnode = self._resolve_citation(builder, refdoc, node, contnode) # no new node found? try the missing-reference event if newnode is None: newnode = builder.app.emit_firstresult( 'missing-reference', self, node, contnode) # still not found? warn if node wishes to be warned about or # we are in nit-picky mode if newnode is None: self._warn_missing_reference(refdoc, typ, target, node, domain) except NoUri: newnode = contnode node.replace_self(newnode or contnode) # remove only-nodes that do not belong to our builder self.process_only_nodes(doctree, builder, fromdocname) # allow custom references to be resolved builder.app.emit('doctree-resolved', doctree, fromdocname)
def doctree_read(app, doctree): env = app.builder.env if not hasattr(env, '_viewcode_modules'): env._viewcode_modules = {} def has_tag(modname, fullname, docname, refname): entry = env._viewcode_modules.get(modname, None) try: analyzer = ModuleAnalyzer.for_module(modname) except Exception: env._viewcode_modules[modname] = False return if not isinstance(analyzer.code, text_type): code = analyzer.code.decode(analyzer.encoding) else: code = analyzer.code if entry is None or entry[0] != code: analyzer.find_tags() entry = code, analyzer.tags, {}, refname env._viewcode_modules[modname] = entry elif entry is False: return _, tags, used, _ = entry if fullname in tags: used[fullname] = docname return True for objnode in doctree.traverse(addnodes.desc): if objnode.get('domain') != 'py': continue names = set() for signode in objnode: if not isinstance(signode, addnodes.desc_signature): continue modname = signode.get('module') fullname = signode.get('fullname') refname = modname if env.config.viewcode_import: modname = _get_full_modname(app, modname, fullname) if not modname: continue fullname = signode.get('fullname') if not has_tag(modname, fullname, env.docname, refname): continue if fullname in names: # only one link per name, please continue names.add(fullname) pagename = '_modules/' + modname.replace('.', '/') onlynode = addnodes.only(expr='html') onlynode += addnodes.pending_xref( '', reftype='viewcode', refdomain='std', refexplicit=False, reftarget=pagename, refid=fullname, refdoc=env.docname) onlynode[0] += nodes.inline('', _('[source]'), classes=['viewcode-link']) signode += onlynode
def assemble_doctree(self, indexfile, toctree_only, appendices): self.docnames = set([indexfile] + appendices) self.info(darkgreen(indexfile) + " ", nonl=1) tree = self.env.get_doctree(indexfile) tree['docname'] = indexfile if toctree_only: # extract toctree nodes from the tree and put them in a # fresh document new_tree = new_document('<latex output>') new_sect = nodes.section() new_sect += nodes.title(u'<Set title in conf.py>', u'<Set title in conf.py>') new_tree += new_sect for node in tree.traverse(addnodes.toctree): new_sect += node tree = new_tree largetree = inline_all_toctrees(self, self.docnames, indexfile, tree, darkgreen, [indexfile]) largetree['docname'] = indexfile for docname in appendices: appendix = self.env.get_doctree(docname) appendix['docname'] = docname largetree.append(appendix) self.info() self.info("resolving references...") self.env.resolve_references(largetree, indexfile, self) # resolve :ref:s to distant tex files -- we can't add a cross-reference, # but append the document name for pendingnode in largetree.traverse(addnodes.pending_xref): docname = pendingnode['refdocname'] sectname = pendingnode['refsectname'] newnodes = [nodes.emphasis(sectname, sectname)] for subdir, title in self.titles: if docname.startswith(subdir): newnodes.append(nodes.Text(_(' (in '), _(' (in '))) newnodes.append(nodes.emphasis(title, title)) newnodes.append(nodes.Text(')', ')')) break else: pass pendingnode.replace_self(newnodes) return largetree
def assemble_doctree(self, indexfile, toctree_only, appendices): self.docnames = set([indexfile] + appendices) self.info(darkgreen(indexfile) + " ", nonl=1) tree = self.env.get_doctree(indexfile) tree['docname'] = indexfile if toctree_only: # extract toctree nodes from the tree and put them in a # fresh document new_tree = new_document('<latex output>') new_sect = nodes.section() new_sect += nodes.title(u'<Set title in conf.py>', u'<Set title in conf.py>') new_tree += new_sect for node in tree.traverse(addnodes.toctree): new_sect += node tree = new_tree largetree = inline_all_toctrees(self, self.docnames, indexfile, tree, darkgreen, []) largetree['docname'] = indexfile for docname in appendices: appendix = self.env.get_doctree(docname) appendix['docname'] = docname largetree.append(appendix) self.info() self.info("resolving references...") self.env.resolve_references(largetree, indexfile, self) # resolve :ref:s to distant tex files -- we can't add a cross-reference, # but append the document name for pendingnode in largetree.traverse(addnodes.pending_xref): docname = pendingnode['refdocname'] sectname = pendingnode['refsectname'] newnodes = [nodes.emphasis(sectname, sectname)] for subdir, title in self.titles: if docname.startswith(subdir): newnodes.append(nodes.Text(_(' (in '), _(' (in '))) newnodes.append(nodes.emphasis(title, title)) newnodes.append(nodes.Text(')', ')')) break else: pass pendingnode.replace_self(newnodes) return largetree
