def xref( typ: str, rawtext: str, text: str, lineno: int, inliner: Inliner, options: dict = None, content: List[str] = None, ) -> Tuple[List[Node], List[system_message]]: title = target = text # look if explicit title and target are given with `foo <bar>` syntax brace = text.find("<") if brace != -1: m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace + 1:] title = text[:brace] link = xref.links[target] if brace != -1: pnode = nodes.reference(target, title, refuri=link[1]) else: pnode = nodes.reference(target, link[0], refuri=link[1]) return [pnode], []
def xref(typ, rawtext, text, lineno, inliner, options={}, content=[]): title = target = text titleistarget = True # look if explicit title and target are given with `foo <bar>` syntax brace = text.find('<') if brace != -1: titleistarget = False m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace + 1:] title = text[:brace] link = xref.links[target] if brace != -1: pnode = nodes.reference(target, title, refuri=link[1]) else: pnode = nodes.reference(target, link[0], refuri=link[1]) return [pnode], []
def xref( typ, rawtext, text, lineno, inliner, options={}, content=[] ): title = target = text titleistarget = True # look if explicit title and target are given with `foo <bar>` syntax brace = text.find('<') if brace != -1: titleistarget = False m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace+1:] title = text[:brace] link = xref.links[target] if brace != -1: pnode = nodes.reference(target, title, refuri=link[1]) else: pnode = nodes.reference(target, link[0], refuri=link[1]) return [pnode], []
def xref(typ, rawtext, text, lineno, inliner, options={}, content=[]): title = target = text brace = text.find('<') if brace != -1: m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: target = text[brace+1:] title = text[:brace] if not (target in xref.links): inliner.reporter.warning("missing xref link '%s'" % target) return [], [] link = xref.links[target] if brace != -1: pnode = nodes.reference(target, title, refuri=link) else: pnode = nodes.reference(target, target, refuri=link) return [pnode], []
def epydoc_role(role, rawtext, text, lineno, inliner, options={}, content=[]): """ Actual role callback """ match = caption_ref_re.match(text) if match: extra, (text, ref) = True, match.group(1, 2) text = text.strip() if text.startswith('|') and text.endswith('|'): text = text[1:-1] extra = False else: extra, text, ref = False, None, text if ref.endswith('()'): ref = ref[:-2].strip() parens = text is None else: parens = False if '/' in ref: chunks = ref.split('/', 1) if not chunks[0]: # Main page uri = 'index.html' else: uri = apis.get(''.join(chunks)) if text is None: text = chunks[1] else: uri = apis.get(ref) if not text: text = ref if parens: text += '()' if uri is None: node = nodes.literal(rawtext, text) else: baseuri = relpath(epydoc, os.path.dirname( inliner.document.current_source)).split( os.path.sep) for idx, elem in enumerate(baseuri): if elem == os.path.curdir: baseuri[idx] = '.' elif elem == os.path.pardir: baseuri[idx] = '..' baseuri = '/'.join(baseuri) uri = posixpath.join(baseuri, uri) if not extra: text = u'\u2192\xa0' + text node = nodes.reference(rawtext, text, refuri=uri, **options) if not extra: node = nodes.literal(rawtext, '', node) return [node], []
def epydoc_role(role, rawtext, text, lineno, inliner, options={}, content=[]): """ Actual role callback """ # pylint: disable = too-many-branches match = caption_ref_re.match(text) if match: extra, (text, ref) = True, match.group(1, 2) text = text.strip() if text.startswith('|') and text.endswith('|'): text = text[1:-1] extra = False else: extra, text, ref = False, None, text if ref.endswith('()'): ref = ref[:-2].strip() parens = text is None else: parens = False if '/' in ref: chunks = ref.split('/', 1) if not chunks[0]: # Main page uri = 'index.html' else: uri = apis.get(''.join(chunks)) if text is None: text = chunks[1] else: uri = apis.get(ref) if not text: text = ref if parens: text += '()' if uri is None: node = nodes.literal(rawtext, text) else: baseuri = relpath( epydoc, os.path.dirname(inliner.document.current_source) ).split(os.path.sep) for idx, elem in enumerate(baseuri): if elem == os.path.curdir: baseuri[idx] = '.' elif elem == os.path.pardir: baseuri[idx] = '..' baseuri = '/'.join(baseuri) uri = posixpath.join(baseuri, uri) if not extra: text = u'\u2192\xa0' + text # pylint: disable = redefined-variable-type node = nodes.reference(rawtext, text, refuri=uri, **options) if not extra: node = nodes.literal(rawtext, '', node) return [node], []
def rcfile_role(role, rawtext, text, lineno, inliner, options={}, content=[]): """Shortcut to return the URL of an *rc file, optionally of a specific version and on a specific line. Usage:: I have written a function that does FOO, see :rc:`line 32 of my barrc <barrc@b1e8bfc81b0a#32>` for the implementation. View my latest :rc:`vimrc`. View line 32 of my latest :rc:`vimrc#32`. :rc:`See all my dotfiles. <*>` """ env = inliner.document.settings.env # Is this a Sphinx-style ref? brace = text.find('<') if brace != -1: m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace + 1:] title = text[:brace] if target == '*': uri = env.config['rc_main'] or env.config['rc_url'] else: # Parse arguments for the rc file like rev and line number rc_string = re_rcfile.search(target) # We didn't get at least a filename, return an error if not rc_string: msg = inliner.reporter.error('Could not parse rc file string.' '"%s" is invalid.' % text, line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] # Get a dict of any params passed for the rc file and build the url tokens = rc_string.groupdict() uri = '%s/%s/%s' % (env.config['rc_url'], tokens.get('revhash') or env.config['rc_head'], tokens['rcfile']) if tokens.get('linenr'): uri += env.config['rc_linenr'] % tokens # Build the actual rST node and return it node = nodes.reference(rawtext, title, refuri=uri, **options) return [node], []
def rcfile_role(role, rawtext, text, lineno, inliner, options={}, content=[]): """Shortcut to return the URL of an *rc file, optionally of a specific version and on a specific line. Usage:: I have written a function that does FOO, see :rc:`line 32 of my barrc <barrc@b1e8bfc81b0a#32>` for the implementation. View my latest :rc:`vimrc`. View line 32 of my latest :rc:`vimrc#32`. :rc:`See all my dotfiles. <*>` """ env = inliner.document.settings.env # Is this a Sphinx-style ref? brace = text.find("<") if brace != -1: m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace + 1 :] title = text[:brace] if target == "*": uri = env.config["rc_main"] or env.config["rc_url"] else: # Parse arguments for the rc file like rev and line number rc_string = re_rcfile.search(target) # We didn't get at least a filename, return an error if not rc_string: msg = inliner.reporter.error("Could not parse rc file string." '"%s" is invalid.' % text, line=lineno) prb = inliner.problematic(rawtext, rawtext, msg) return [prb], [msg] # Get a dict of any params passed for the rc file and build the url tokens = rc_string.groupdict() uri = "%s/%s/%s" % (env.config["rc_url"], tokens.get("revhash") or env.config["rc_head"], tokens["rcfile"]) if tokens.get("linenr"): uri += env.config["rc_linenr"] % tokens # Build the actual rST node and return it node = nodes.reference(rawtext, title, refuri=uri, **options) return [node], []
def toctree_directive(name, arguments, options, content, lineno, content_offset, block_text, state, state_machine): env = state.document.settings.env suffix = env.config.source_suffix dirname = posixpath.dirname(env.docname) glob = 'glob' in options ret = [] subnode = addnodes.toctree() includefiles = [] includetitles = {} all_docnames = env.found_docs.copy() # don't add the currently visited file in catch-all patterns all_docnames.remove(env.docname) for entry in content: if not entry: continue if not glob: # look for explicit titles and documents ("Some Title <document>"). m = caption_ref_re.match(entry) if m: docname = m.group(2) includetitles[docname] = m.group(1) else: docname = entry # remove suffixes (backwards compatibility) if docname.endswith(suffix): docname = docname[:-len(suffix)] # absolutize filenames docname = posixpath.normpath(posixpath.join(dirname, docname)) if docname not in env.found_docs: ret.append(state.document.reporter.warning( 'toctree references unknown document %r' % docname, line=lineno)) else: includefiles.append(docname) else: patname = posixpath.normpath(posixpath.join(dirname, entry)) docnames = sorted(patfilter(all_docnames, patname)) for docname in docnames: all_docnames.remove(docname) # don't include it again includefiles.append(docname) if not docnames: ret.append(state.document.reporter.warning( 'toctree glob pattern %r didn\'t match any documents' % entry, line=lineno)) subnode['includefiles'] = includefiles subnode['includetitles'] = includetitles subnode['maxdepth'] = options.get('maxdepth', -1) subnode['glob'] = glob ret.append(subnode) return ret
def epydoc_role(role, rawtext, text, lineno, inliner, options={}, content=[]): """ Actual role callback """ match = caption_ref_re.match(text) if match: extra, (text, ref) = True, match.group(1, 2) text = text.strip() if text.startswith("|") and text.endswith("|"): text = text[1:-1] extra = False else: extra, text, ref = False, None, text if ref.endswith("()"): ref = ref[:-2].strip() parens = text is None else: parens = False if "/" in ref: chunks = ref.split("/", 1) if not chunks[0]: # Main page uri = "index.html" else: uri = apis.get("".join(chunks)) if text is None: text = chunks[1] else: uri = apis.get(ref) if not text: text = ref if parens: text += "()" if uri is None: node = nodes.literal(rawtext, text) else: baseuri = relpath(epydoc, os.path.dirname(inliner.document.current_source)).split(os.path.sep) for idx, elem in enumerate(baseuri): if elem == os.path.curdir: baseuri[idx] = "." elif elem == os.path.pardir: baseuri[idx] = ".." baseuri = "/".join(baseuri) uri = posixpath.join(baseuri, uri) if not extra: text = u"\u2192\xa0" + text node = nodes.reference(rawtext, text, refuri=uri, **options) if not extra: node = nodes.literal(rawtext, "", node) return [node], []
def split_explicit_title(text): """Split role content into title and target, if given.""" brace = text.find('<') if brace != -1: m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace + 1:] title = text[:brace] return True, title, target else: return False, text, text
def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): env = inliner.document.settings.env if not typ: typ = env.config.default_role else: typ = typ.lower() text = utils.unescape(text) # if the first character is a bang, don't cross-reference at all if text[0:1] == '!': text = _fix_parens(typ, text[1:], env) return [innernodetypes.get(typ, nodes.literal)( rawtext, text, classes=['xref'])], [] # we want a cross-reference, create the reference node pnode = addnodes.pending_xref(rawtext, reftype=typ, refcaption=False, modname=env.currmodule, classname=env.currclass) # we may need the line number for warnings pnode.line = lineno # the link title may differ from the target, but by default they are the same title = target = text titleistarget = True # look if explicit title and target are given with `foo <bar>` syntax brace = text.find('<') if brace != -1: titleistarget = False pnode['refcaption'] = True m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace+1:] title = text[:brace] # special target for Python object cross-references if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod', 'obj'): # fix-up parentheses in link title if titleistarget: title = title.lstrip('.') # only has a meaning for the target target = target.lstrip('~') # only has a meaning for the title title = _fix_parens(typ, title, env) # if the first character is a tilde, don't display the module/class # parts of the contents if title[0:1] == '~': title = title[1:] dot = title.rfind('.') if dot != -1: title = title[dot+1:] # remove parentheses from the target too if target.endswith('()'): target = target[:-2] # if the first character is a dot, search more specific namespaces first # else search builtins first if target[0:1] == '.': target = target[1:] pnode['refspecific'] = True # some other special cases for the target elif typ == 'option': program = env.currprogram if titleistarget: if ' ' in title and not (title.startswith('/') or title.startswith('-')): program, target = re.split(' (?=-|--|/)', title, 1) program = ws_re.sub('-', program) target = target.strip() elif ' ' in target: program, target = re.split(' (?=-|--|/)', target, 1) program = ws_re.sub('-', program) pnode['refprogram'] = program elif typ == 'term': # normalize whitespace in definition terms (if the term reference is # broken over a line, a newline will be in target) target = ws_re.sub(' ', target).lower() elif typ == 'ref': # reST label names are always lowercased target = ws_re.sub('', target).lower() else: # remove all whitespace to avoid referencing problems target = ws_re.sub('', target) pnode['reftarget'] = target pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, classes=['xref']) return [pnode], []
def run(self): env = self.state.document.settings.env suffix = env.config.source_suffix glob = 'glob' in self.options ret = [] # (title, ref) pairs, where ref may be a document, or an external link, # and title may be None if the document's title is to be used entries = [] includefiles = [] includetitles = {} all_docnames = env.found_docs.copy() # don't add the currently visited file in catch-all patterns all_docnames.remove(env.docname) for entry in self.content: if not entry: continue if not glob: # look for explicit titles ("Some Title <document>") m = caption_ref_re.match(entry) if m: ref = m.group(2) title = m.group(1) docname = ref else: ref = docname = entry title = None # remove suffixes (backwards compatibility) if docname.endswith(suffix): docname = docname[:-len(suffix)] # absolutize filenames docname = docname_join(env.docname, docname) if url_re.match(ref) or ref == 'self': entries.append((title, ref)) elif docname not in env.found_docs: ret.append( self.state.document.reporter.warning( 'toctree references unknown document %r' % docname, line=self.lineno)) else: entries.append((title, docname)) includefiles.append(docname) else: patname = docname_join(env.docname, entry) docnames = sorted(patfilter(all_docnames, patname)) for docname in docnames: all_docnames.remove(docname) # don't include it again entries.append((None, docname)) includefiles.append(docname) if not docnames: ret.append( self.state.document.reporter.warning( 'toctree glob pattern %r didn\'t match any documents' % entry, line=self.lineno)) subnode = addnodes.toctree() subnode['parent'] = env.docname # entries contains all entries (self references, external links etc.) subnode['entries'] = entries # includefiles only entries that are documents subnode['includefiles'] = includefiles subnode['maxdepth'] = self.options.get('maxdepth', -1) subnode['glob'] = glob subnode['hidden'] = 'hidden' in self.options subnode['numbered'] = 'numbered' in self.options ret.append(subnode) return ret
def xfileref_role(typ, rawtext, text, lineno, inliner, options={}, content=[]): env = inliner.document.settings.env if not typ: typ = env.config.default_role else: typ = typ.lower() text = utils.unescape(text) # if the first character is a bang, don't cross-reference at all if text[0:1] == '!': text = _fix_parens(typ, text[1:], env) return [ innernodetypes.get(typ, nodes.literal)(rawtext, text, classes=['xref']) ], [] # we want a cross-reference, create the reference node nodeclass = (typ == 'download') and addnodes.download_reference or \ addnodes.pending_xref pnode = nodeclass(rawtext, reftype=typ, refcaption=False, modname=env.currmodule, classname=env.currclass) # we may need the line number for warnings pnode.line = lineno # the link title may differ from the target, but by default # they are the same title = target = text titleistarget = True # look if explicit title and target are given with `foo <bar>` syntax brace = text.find('<') if brace != -1: titleistarget = False pnode['refcaption'] = True m = caption_ref_re.match(text) if m: target = m.group(2) title = m.group(1) else: # fallback: everything after '<' is the target target = text[brace + 1:] title = text[:brace] # special target for Python object cross-references if typ in ('data', 'exc', 'func', 'class', 'const', 'attr', 'meth', 'mod', 'obj'): # fix-up parentheses in link title if titleistarget: title = title.lstrip('.') # only has a meaning for the target target = target.lstrip('~') # only has a meaning for the title title = _fix_parens(typ, title, env) # if the first character is a tilde, don't display the module/class # parts of the contents if title[0:1] == '~': title = title[1:] dot = title.rfind('.') if dot != -1: title = title[dot + 1:] # remove parentheses from the target too if target.endswith('()'): target = target[:-2] # if the first character is a dot, search more specific namespaces first # else search builtins first if target[0:1] == '.': target = target[1:] pnode['refspecific'] = True # some other special cases for the target elif typ == 'option': program = env.currprogram if titleistarget: if ' ' in title and not (title.startswith('/') or title.startswith('-')): program, target = re.split(' (?=-|--|/)', title, 1) program = ws_re.sub('-', program) target = target.strip() elif ' ' in target: program, target = re.split(' (?=-|--|/)', target, 1) program = ws_re.sub('-', program) pnode['refprogram'] = program elif typ == 'term': # normalize whitespace in definition terms (if the term reference is # broken over a line, a newline will be in target) target = ws_re.sub(' ', target).lower() elif typ == 'ref': # reST label names are always lowercased target = ws_re.sub('', target).lower() elif typ == 'cfunc': # fix-up parens for C functions too if titleistarget: title = _fix_parens(typ, title, env) # remove parentheses from the target too if target.endswith('()'): target = target[:-2] else: # remove all whitespace to avoid referencing problems target = ws_re.sub('', target) pnode['reftarget'] = target pnode += innernodetypes.get(typ, nodes.literal)(rawtext, title, classes=['xref']) return [pnode], []
def run(self): env = self.state.document.settings.env suffix = env.config.source_suffix glob = 'glob' in self.options ret = [] # (title, ref) pairs, where ref may be a document, or an external link, # and title may be None if the document's title is to be used entries = [] includefiles = [] includetitles = {} all_docnames = env.found_docs.copy() # don't add the currently visited file in catch-all patterns all_docnames.remove(env.docname) for entry in self.content: if not entry: continue if not glob: # look for explicit titles ("Some Title <document>") m = caption_ref_re.match(entry) if m: ref = m.group(2) title = m.group(1) docname = ref else: ref = docname = entry title = None # remove suffixes (backwards compatibility) if docname.endswith(suffix): docname = docname[:-len(suffix)] # absolutize filenames docname = docname_join(env.docname, docname) if url_re.match(ref) or ref == 'self': entries.append((title, ref)) # elif docname not in env.found_docs: # ret.append(self.state.document.reporter.warning( # 'toctree references unknown document %r' % docname, # line=self.lineno)) else: entries.append((title, docname)) includefiles.append(docname) else: patname = docname_join(env.docname, entry) docnames = sorted(patfilter(all_docnames, patname)) for docname in docnames: all_docnames.remove(docname) # don't include it again entries.append((None, docname)) includefiles.append(docname) if not docnames: ret.append(self.state.document.reporter.warning( 'toctree glob pattern %r didn\'t match any documents' % entry, line=self.lineno)) subnode = addnodes.toctree() subnode['parent'] = env.docname # entries contains all entries (self references, external links etc.) subnode['entries'] = entries # includefiles only entries that are documents subnode['includefiles'] = includefiles subnode['maxdepth'] = self.options.get('maxdepth', -1) subnode['glob'] = glob subnode['hidden'] = 'hidden' in self.options subnode['numbered'] = 'numbered' in self.options ret.append(subnode) return ret