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 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
