def blogref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Inserts a reference to the blog entry of the specified date.
Instead of writing ``:doc:`/blog/2011/0406```
it is better to write ``:blogref:`20110406```
because the latter works between Sphinx trees and also supports archived blog entries.
"""
# thanks to http://docutils.sourceforge.net/docs/howto/rst-roles.html
# this code originally from roles.pep_reference_role
#~ print 20130315, rawtext, text, utils.unescape(text)
has_explicit_title, title, target = split_explicit_title(text)
try:
date = i2d(int(target))
except ValueError:
msg = inliner.reporter.error(
'Invalid text %r: must be an integer date of style "20130315" .'
% text, line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
#~ print repr(env)
#~ raise Exception(20130315)
#~ ref = inliner.document.settings.pep_base_url
#~ + inliner.document.settings.pep_file_url_template % date)
roles.set_classes(options)
#~ from django.conf import settings
#~ shown_text = settings.SITE.dtos(date)
env = inliner.document.settings.env
if not has_explicit_title:
title = date.strftime(env.settings.get('today_fmt', '%Y-%m-%d'))
title = utils.unescape(title)
return [nodes.reference(rawtext, title,
refuri=get_blog_url(date),
**options)], []
def run(self):
set_classes(self.options)
span_text = self.arguments[0]
textnodes, messages = self.state.inline_text(span_text, self.lineno)
_span_node = span(span_text, '', *textnodes, **self.options)
self.add_name(_span_node)
return [_span_node] + messages
def run(self):
classes = self.options.get('class', [])
classes.extend(self.options.get('header_class', '').split(' '))
self.options['class'] = classes
set_classes(self.options)
self.assert_has_content()
text = '\n'.join(self.content)
admonition_node = self.node_class(text, **self.options)
self.add_name(admonition_node)
if self.node_class is nodes.admonition:
title_text = self.arguments[0]
textnodes, messages = self.state.inline_text(title_text,
self.lineno)
admonition_node += nodes.title(title_text, '', *textnodes)
admonition_node += messages
if not 'classes' in self.options:
admonition_node['classes'] += [
'admonition-' + nodes.make_id(title_text)
]
body = nodes.container(
classes=self.options.get('body_class', '').split(' ')
)
self.state.nested_parse(self.content, self.content_offset, body)
return [admonition_node, body]
def generate_uri_role( role_name, aliases,
anchor_text, base_url,
interpret_url, validator):
'''Creates and register a uri based "interpreted role".
Those are similar to the RFC, and PEP ones, and take
role_name:
name that will be registered
aliases:
list of alternate names
anchor_text:
text that will be used, together with the role
base_url:
base url for the link
interpret_url:
this, modulo the validated text, will be added to it
validator:
should return the validated text, or raise ValueError
'''
def uri_reference_role(role, rawtext, text, lineno, inliner,
options={}, content=[]):
try:
valid_text = validator(text)
except ValueError, e:
msg = inliner.reporter.error( e.message % dict(text=text), line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
ref = base_url + interpret_url % valid_text
set_classes(options)
node = nodes.reference(rawtext, anchor_text + utils.unescape(text), refuri=ref,
**options)
return [node], []
def make_link_node(rawtext, app, type, slug, options):
"""Create a link to a github resource.
:param rawtext: Text being replaced with link node.
:param app: Sphinx application context
:param type: Link type (issues, changeset, etc.)
:param slug: ID of the thing to link to
:param options: Options dictionary passed to role func.
"""
try:
base = app.config.github_project_url
if not base:
raise AttributeError
if not base.endswith('/'):
base += '/'
except AttributeError as err:
raise ValueError('github_project_url configuration value is not set (%s)' % str(err))
ref = base + type + '/' + slug + '/'
set_classes(options)
prefix = "#"
if type == 'pull':
prefix = "PR " + prefix
node = nodes.reference(rawtext, prefix + utils.unescape(slug), refuri=ref,
**options)
return node
def verse_reference_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
#print(role,' - ',rawtext,' - ',text,file=sys.stderr)
env = inliner.document.settings.env
bible_version = env.app.config.bible_version
if bible_version not in version_reference_functions:
raise Exception("Unknown bible version. I don't know about "+bible_version)
bibleref_function = version_reference_functions[bible_version]
p = Parser(text)
try:
vrlist = p.parse_verse_references()
except ParseException as pe:
msg = inliner.reporter.error("Exception parsing '"+text+"':"+str(pe), line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
nodels = []
roles.set_classes(options)
for vr in vrlist:
#print('refuri is',bibleref_function(vr),file=sys.stderr)
#print('opts:',options)
node = nodes.reference(rawtext, vr.text, internal=False, refuri=bibleref_function(vr), **options)
nodels.append(node)
nodels.append(nodes.generated(', ',', ', **options))
if len(nodels) > 1:
del nodels[-1] # delete last comma
return nodels,[]
def extensionpoints_role(name, rawtext, text, lineno, inliner, options={},
content=[]):
ref = url + '/wiki/TracDev/PluginDevelopment/ExtensionPoints/' + text
roles.set_classes(options)
node = nodes.reference(rawtext, text + " extension points",
refuri=ref, **options)
return [node], []
def bokeh_tree(name, rawtext, text, lineno, inliner, options=None, content=None):
""" Link to a URL in the Bokeh GitHub tree, pointing to appropriate tags
for releases, or to master otherwise.
The link text is simply the URL path supplied, so typical usage might
look like:
.. code-block:: none
All of the examples are located in the :bokeh-tree:`examples`
subdirectory of your Bokeh checkout.
Returns 2 part tuple containing list of nodes to insert into the
document and a list of system messages. Both are allowed to be
empty.
"""
app = inliner.document.settings.env.app
tag = app.env.config['version']
if '-' in tag:
tag = 'master'
url = "%s/tree/%s/%s" % (BOKEH_GH, tag, text)
_try_url(app, url, 'tree')
options = options or {}
set_classes(options)
node = nodes.reference(
rawtext, text, refuri=url, **options)
return [node], []
def run(self):
set_classes(self.options)
rubric_text = self.arguments[0]
textnodes, messages = self.state.inline_text(rubric_text, self.lineno)
rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
self.add_name(rubric)
return [rubric] + messages
def run(self):
# largely lifted from the superclass in order to make titles work
set_classes(self.options)
# self.assert_has_content()
text = '\n'.join(self.content)
admonition_node = self.node_class(text, **self.options)
self.add_name(admonition_node)
if self.arguments:
title_text = self.arguments[0]
textnodes, messages = self.state.inline_text(title_text,
self.lineno)
admonition_node += nodes.title(title_text, '', *textnodes)
admonition_node += messages
else:
# no title, make something up so we have an ID
title_text = str(hash(' '.join(self.content)))
if not 'classes' in self.options:
admonition_node['classes'] += ['admonition-' +
nodes.make_id(title_text)]
self.state.nested_parse(self.content, self.content_offset,
admonition_node)
return [admonition_node]
def run(self):
""" build rv_code node """
set_classes(self.options)
self.assert_has_content()
node = self.node_class('\n'.join(self.content), **self.options)
return [node]
def link(name, rawtext, text, lineno, inliner, options={}, content=[]):
title, url = parse_link(text)
if not title: title = url
# TODO: mailto URLs, internal links (need to gut out docutils for that)
set_classes(options)
node = nodes.reference(rawtext, title, refuri=url, **options)
return [node], []
def github_link(
name, rawtext, text, lineno, inliner, options=None, content=None
):
app = inliner.document.settings.env.app
release = app.config.release
base_url = 'https://github.com/pallets/flask/tree/'
if text.endswith('>'):
words, text = text[:-1].rsplit('<', 1)
words = words.strip()
else:
words = None
if release.endswith('dev'):
url = '{0}master/{1}'.format(base_url, text)
else:
url = '{0}{1}/{2}'.format(base_url, release, text)
if words is None:
words = url
from docutils.nodes import reference
from docutils.parsers.rst.roles import set_classes
options = options or {}
set_classes(options)
node = reference(rawtext, words, refuri=url, **options)
return [node], []
def vkext(name, rawtext, text, lineno, inliner, options={}, content=[]):
title, extension = parse_link(text)
if not title: title = extension
url = "https://www.khronos.org/registry/vulkan/specs/1.1-extensions/html/vkspec.html#VK_{}".format(extension)
set_classes(options)
node = nodes.reference(rawtext, title, refuri=url, **options)
return [node], []
def blogref_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
# thanks to http://docutils.sourceforge.net/docs/howto/rst-roles.html
# this code originally from roles.pep_reference_role
#~ print 20130315, rawtext, text, utils.unescape(text)
has_explicit_title, title, target = split_explicit_title(text)
try:
date = i2d(int(target))
except ValueError:
msg = inliner.reporter.error(
'Invalid text %r: must be an integer date of style "20130315" .'
% text, line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
#~ print repr(env)
#~ raise Exception(20130315)
#~ ref = inliner.document.settings.pep_base_url
#~ + inliner.document.settings.pep_file_url_template % date)
roles.set_classes(options)
#~ from django.conf import settings
#~ shown_text = settings.SITE.dtos(date)
env = inliner.document.settings.env
if not has_explicit_title:
title = date.strftime(env.settings.get('today_fmt', '%Y-%m-%d'))
title = utils.unescape(title)
return [nodes.reference(rawtext, title,
refuri=get_blog_url(env, date),
**options)], []
def run(self):
set_classes(self.options)
self.assert_has_content()
latex_code = '\n'.join(self.content)
node = nodes.math_block(self.block_text, latex_code, **self.options)
node.line = self.content_offset + 1
return [node]
def make_link_node(rawtext, app, notebook, options):
base = 'https://github.com/gammapy/gammapy-extra/tree/master/notebooks/'
full_name = notebook + '.ipynb'
ref = base + full_name
roles.set_classes(options)
node = nodes.reference(rawtext, full_name, refuri=ref, **options)
return node
def code(role, rawtext, text, lineno, inliner, options={}, content=[]):
# In order to properly preserve backslashes
i = rawtext.find('`')
text = rawtext.split('`')[1]
set_classes(options)
classes = []
if 'classes' in options:
classes += options['classes']
del options['classes']
# If language is not specified, render a simple literal
if not 'language' in options:
content = nodes.raw('', utils.unescape(text), format='html')
node = nodes.literal(rawtext, '', **options)
node.append(content)
return [node], []
language = options['language']
del options['language']
# Not sure why language is duplicated in classes?
if language in classes: classes.remove(language)
class_, highlighted = _highlight(utils.unescape(text), language, options, is_block=False)
classes += [class_]
content = nodes.raw('', highlighted, format='html')
node = nodes.literal(rawtext, '', classes=classes, **options)
node.append(content)
return [node], []
def make_gh_link_node(app, rawtext, role, kind, api_type, id, options={}):
""" Return a link to a Bokeh Github resource.
Args:
app (Sphinx app) : current app
rawtext (str) : text being replaced with link node.
role (str) : role name
kind (str) : resource type (issue, pull, etc.)
api_type (str) : type for api link
id : (str) : id of the resource to link to
options (dict) : options dictionary passed to role function
"""
url = "%s/%s/%s" % (BOKEH_GH, api_type, id)
try:
request = urllib.request.Request(url)
request.get_method = lambda: "HEAD"
response = urllib.request.urlopen(request, timeout=5)
except (urllib.error.HTTPError, urllib.error.URLError):
app.warn("URL '%s' for :bokeh-%s: role could not be loaded" % (url, role))
else:
if response.getcode() >= 400:
app.warn("URL '%s' for :bokeh-%s: role could not be loaded" % (url, role))
set_classes(options)
node = nodes.reference(rawtext, kind + " " + utils.unescape(id), refuri=url, **options)
return node
def btn_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
m = re.match(r'(.*)\<(.*)\>(,.*){0,}', text)
if m:
name, ref, classes = m.groups()
if ref is '':
msg = inliner.reporter.error('The ref portion of the btn role'
' cannot be none')
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
ref_cls = []
em_cls = []
if classes:
cls = classes.strip(',').split(',')
em_cls = [x for x in cls if x.startswith("icon-")]
ref_cls = [x for x in cls if not x.startswith("icon-")]
if 'btn' not in ref_cls:
ref_cls.append('btn')
options.update({'classes': ref_cls})
set_classes(options)
node = reference(rawtext, name, refuri=ref, **options)
if len(em_cls) > 0:
em_cls.append('icon-holder')
em_opts = {'classes': em_cls}
set_classes(em_opts)
node.insert(0, emphasis(**em_opts))
node.insert(1, Text(" "))
return [node], []
def page_attachment(role, rawtext, text, lineno, inliner, options={}, content=[]):
"""
Role to make a reference link to a Page's attachment
Usage in document :
Blah blah :attachment:`idX-slug`
Where X is the page id and slug his slugname
The page id is needed because i can't find a clean way to give some page context to
the docutils parser.
"""
matched = _ATTACHMENT_ROLE_REGEX.match(text)
if not matched or len(matched.groups())<2:
return rst_parser_error('Attachment role syntax is not respected with "{0}", you should write something like "idXX-ATTACHMENT_SLUG".'.format(text), rawtext, text, lineno, inliner)
# Get the page slugs map
pk, attachment_slug = matched.groups()
try:
slugs_map = get_page_attachment_slugs(pk)
except Page.DoesNotExist:
return rst_parser_error('Page with id "{pk}" does not exist in pattern "{pattern}"'.format(pk=pk, pattern=text), rawtext, text, lineno, inliner)
else:
if attachment_slug not in slugs_map and not settings.DOCUMENTS_PARSER_WIKIROLE_SILENT_WARNING:
return rst_parser_error('Attachment with slug "{slug}" does not exist for page id "{pk}" in pattern "{pattern}".'.format(pk=pk, slug=attachment_slug, pattern=text), rawtext, text, lineno, inliner)
link = slugs_map[attachment_slug]
# Add a class to the item
options.update({'classes': ['documents_page_attachment']})
roles.set_classes(options)
# Return the node as reference to display the link for the given page's slug
node = nodes.reference(rawtext, utils.unescape(attachment_slug), refuri=os.path.join(settings.MEDIA_URL, link), **options)
return [node], []
def run(self):
set_classes(self.options)
# FFS why so complex
svg = qrcode.make(self.arguments[0], image_factory=qrcode.image.svg.SvgPathFillImage)
f = io.BytesIO()
svg.save(f)
svg = f.getvalue().decode('utf-8')
# Compress a bit, remove cruft
svg = svg.replace('L ', 'L').replace('M ', 'M').replace(' z', 'z')
svg = svg.replace(' id="qr-path"', '')
attribs = ' class="{}"'.format(' '.join(['m-image'] + self.options.get('classes', [])))
if 'size' in self.options:
size = self.options['size']
else:
size = None
def preamble_repl(match): return _svg_preamble_dst.format(
attribs=attribs,
size=size if size else
# The original size is in mm, convert that to pixels on 96 DPI
# and then to rem assuming 1 rem = 16px
'{:.2f}rem'.format(float(match.group('width'))*9.6/2.54/16.0, 2),
viewBox=match.group('viewBox'))
svg = _svg_preamble_src.sub(preamble_repl, svg)
return [nodes.raw('', svg, format='html')]
def glfn(name, rawtext, text, lineno, inliner, options={}, content=[]):
title, fn = parse_link(text)
if not title: title = "gl{}()".format(fn)
url = "https://www.khronos.org/registry/OpenGL-Refpages/gl4/html/gl{}.xhtml".format(fn)
set_classes(options)
node = nodes.reference(rawtext, title, refuri=url, **options)
return [node], []
def glfnext(name, rawtext, text, lineno, inliner, options={}, content=[]):
title, extension = parse_link(text)
prefix = extension.partition('_')[0]
url = "https://www.khronos.org/registry/OpenGL/extensions/{}/{}.txt".format(prefix, extension)
set_classes(options)
node = nodes.reference(rawtext, "gl" + title + prefix + "()", refuri=url, **options)
return [node], []
def redhat_bugzilla_role(role, rawtext, text, lineno, inliner,
options={}, content=[]):
"""
Implementation of Red Hat Bugzilla referencing role.
Usage::
See :BZ:`439858` for more information.
"""
try:
bznum = int(text)
if bznum <= 0:
raise ValueError
except ValueError:
msg = inliner.reporter.error(
'BZ number must be a number greater than or equal to 1; '
'"%s" is invalid.' % text, line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
# TODO: make base url configurable
ref = "https://bugzilla.redhat.com/show_bug.cgi?id={0:d}".format(bznum)
roles.set_classes(options)
node = nodes.reference(
rawtext, 'BZ ' + utils.unescape(text), refuri=ref, **options)
return [node], []
def webglext(name, rawtext, text, lineno, inliner, options={}, content=[]):
title, extension = parse_link(text)
if not title: title = extension
url = "https://www.khronos.org/registry/webgl/extensions/{}/".format(extension)
set_classes(options)
node = nodes.reference(rawtext, title, refuri=url, **options)
return [node], []
def math(role, rawtext, text, lineno, inliner, options={}, content=[]):
# Otherwise the backslashes do quite a mess there
i = rawtext.find('`')
text = rawtext.split('`')[1]
# Fallback rendering as code requested
if settings['M_MATH_RENDER_AS_CODE']:
set_classes(options)
classes = []
if 'classes' in options:
classes += options['classes']
del options['classes']
content = nodes.raw('', html.escape(utils.unescape(text)), format='html')
node = nodes.literal(rawtext, '', **options)
node.append(content)
return [node], []
# Apply classes to the <svg> element instead of some outer <span>
set_classes(options)
classes = 'm-math'
if 'classes' in options:
classes += ' ' + ' '.join(options['classes'])
del options['classes']
depth, svg = latex2svgextra.fetch_cached_or_render("$" + text + "$")
attribs = ' class="{}"'.format(classes)
node = nodes.raw(rawtext, latex2svgextra.patch(text, svg, depth, attribs), format='html', **options)
return [node], []
def vktype(name, rawtext, text, lineno, inliner, options={}, content=[]):
title, fn = parse_link(text)
if not title: title = "Vk{}".format(fn)
url = "https://www.khronos.org/registry/vulkan/specs/1.1-extensions/man/html/Vk{}.html".format(fn)
set_classes(options)
node = nodes.reference(rawtext, title, refuri=url, **options)
return [node], []
def icon_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
options.update({'classes': ["icon-" + x for x in text.split(",")]})
options['classes'].append('icon-holder')
set_classes(options)
node = emphasis(**options)
return [node], []
def run(self):
set_classes(self.options)
text = '\n'.join(self.content)
figure_node = nodes.figure(text, **self.options)
figure_node['classes'] += self.style_classes
self.state.nested_parse(self.content, self.content_offset,
figure_node)
# Insert the title node, if any, right after the code / math / graph.
# There could be things like the class directive before, so be sure to
# find the right node.
if len(self.arguments) == 1:
title_text = self.arguments[0]
title_nodes, _ = self.state.inline_text(title_text, self.lineno)
title_node = nodes.caption('', '', *title_nodes)
for i, child in enumerate(figure_node):
if isinstance(child, nodes.raw) or isinstance(child, nodes.literal_block):
figure_node.insert(i + 1, title_node)
break
else: assert False # pragma: no cover
return [figure_node]
def run(self):
set_classes(self.options)
# Type
assert self.options['type'] == 'barh'
# Graph title and axis labels. Value labels are one per line.
title = self.arguments[0]
units = self.options['units']
labels = self.options['labels'].split('\n')
# Optional extra labels
if 'labels_extra' in self.options:
labels_extra = self.options['labels_extra'].split('\n')
assert len(labels_extra) == len(labels)
else:
labels_extra = None
# Values. Should be one for each label.
values = [float(v) for v in self.options['values'].split()]
assert len(values) == len(labels)
# Optional errors
if 'errors' in self.options:
errors = [float(e) for e in self.options['errors'].split()]
else:
errors = None
# Colors. Should be either one for all or one for every value
colors = [
style_mapping[c]
for c in self.options.get('colors', 'default').split()
]
if len(colors) == 1: colors = colors[0]
else: assert len(colors) == len(labels)
# Bar height
bar_height = float(self.options.get('bar_height', '0.4'))
# Increase hashsalt for every plot to ensure (hopefully) unique SVG IDs
mpl.rcParams['svg.hashsalt'] = int(mpl.rcParams['svg.hashsalt']) + 1
# Setup the graph
fig, ax = plt.subplots()
# TODO: let matplotlib calculate the height somehow
fig.set_size_inches(8, 0.78 + len(values) * bar_height)
yticks = np.arange(len(labels))
plot = ax.barh(yticks,
values,
xerr=errors,
align='center',
color=colors,
ecolor='#cafe0a',
capsize=5 * bar_height / 0.4)
for i, v in enumerate(plot):
v.set_gid('plot{}-value{}'.format(mpl.rcParams['svg.hashsalt'], i))
ax.set_yticks(yticks)
ax.invert_yaxis() # top-to-bottom
ax.set_xlabel(units)
ax.set_title(title)
# Value labels. If extra label is specified, create two multiline texts
# with first having the second line empty and second having the first
# line empty.
if labels_extra:
ax.set_yticklabels([y + '\n' for y in labels])
for i, label in enumerate(ax.get_yticklabels()):
ax.text(0,
i + 0.05,
'\n' + labels_extra[i],
va='center',
ha='right',
transform=label.get_transform(),
color='#cafe0b')
else:
ax.set_yticklabels(labels)
# Export to SVG
fig.patch.set_visible(False) # hide the white background
imgdata = io.StringIO()
fig.savefig(imgdata, format='svg')
plt.close() # otherwise it consumes a lot of memory in autoreload mode
# Patch the rendered output: remove preable and hardcoded size
imgdata = _patch_src.sub(_patch_dst, imgdata.getvalue())
# Remove needless newlines and trailing whitespace in path data
imgdata = _path_patch2_src.sub(
_path_patch2_dst, _path_patch_src.sub(_path_patch_dst, imgdata))
# Replace color codes with CSS classes
for src, dst in _class_mapping:
imgdata = imgdata.replace(src, dst)
# Add titles for bars
for i in range(len(values)):
if errors:
imgdata = imgdata.replace(
_bar_titles_src.format(mpl.rcParams['svg.hashsalt'], i),
_bar_titles_dst_error.format(mpl.rcParams['svg.hashsalt'],
i, values[i], errors[i],
units))
else:
imgdata = imgdata.replace(
_bar_titles_src.format(mpl.rcParams['svg.hashsalt'], i),
_bar_titles_dst.format(mpl.rcParams['svg.hashsalt'], i,
values[i], units))
container = nodes.container(**self.options)
container['classes'] += ['m-plot']
node = nodes.raw('', imgdata, format='html')
container.append(node)
return [container]
def run(self):
messages = []
reference = directives.uri(self.arguments[0])
self.options['uri'] = reference
reference_node = None
if 'target' in self.options:
block = states.escape2null(self.options['target']).splitlines()
block = [line for line in block]
target_type, data = self.state.parse_target(
block, self.block_text, self.lineno)
if target_type == 'refuri':
reference_node = nodes.reference(refuri=data)
elif target_type == 'refname':
reference_node = nodes.reference(
refname=fully_normalize_name(data),
name=whitespace_normalize_name(data))
reference_node.indirect_reference_name = data
self.state.document.note_refname(reference_node)
else: # malformed target
messages.append(data) # data is a system message
del self.options['target']
width = None
height = None
# If scaling requested, open the files and calculate the scaled size
# Support both {filename} (3.7.1) and {static} (3.8) placeholders,
# also prepend the absolute path in case we're not Pelican. In all
# cases use only width and not both so the max-width can correctly
# scale the image down on smaller screen sizes.
# TODO: implement ratio-preserving scaling to avoid jumps on load using
# the margin-bottom hack
if 'scale' in self.options:
file = os.path.join(os.getcwd(), settings['INPUT'])
absuri = os.path.join(file,
reference.format(filename=file, static=file))
im = PIL.Image.open(absuri)
width = "{}px".format(int(im.width * self.options['scale'] /
100.0))
elif 'width' in self.options:
width = self.options['width']
elif 'height' in self.options:
height = self.options['height'] # TODO: convert to width instead?
# Remove the classes from the image element, will be added either to it
# or to the wrapping element later
set_classes(self.options)
classes = self.options.get('classes', [])
if 'classes' in self.options: del self.options['classes']
if 'width' in self.options: del self.options['width']
if 'height' in self.options: del self.options['height']
image_node = nodes.image(self.block_text,
width=width,
height=height,
**self.options)
if not 'alt' in self.options and settings['M_IMAGES_REQUIRE_ALT_TEXT']:
error = self.state_machine.reporter.error(
'Images and figures require the alt text. See the M_IMAGES_REQUIRE_ALT_TEXT option.',
image_node,
line=self.lineno)
return [error]
self.add_name(image_node)
if reference_node:
if self.image_class:
container_node = nodes.container()
container_node['classes'] += [self.image_class] + classes
reference_node += image_node
container_node += reference_node
return messages + [container_node]
else:
reference_node += image_node
return messages + [reference_node]
else:
if self.image_class:
image_node['classes'] += [self.image_class] + classes
return messages + [image_node]
def commit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
ref = 'https://github.com/scrapy/scrapy/commit/' + text
set_classes(options)
node = nodes.reference(rawtext, 'commit ' + text, refuri=ref, **options)
return [node], []
def abbr(name, rawtext, text, lineno, inliner, options={}, content=[]):
abbr, title = parse_link(text)
set_classes(options)
if not abbr:
return [nodes.abbreviation(title, title, **options)], []
return [nodes.abbreviation(abbr, abbr, title=title, **options)], []
def dox(name, rawtext, text, lineno, inliner: Inliner, options={}, content=[]):
title, target, hash = parse_link(text)
# Otherwise adding classes to the options behaves globally (uh?)
_options = dict(options)
set_classes(_options)
# Avoid assert on adding to undefined member later
if 'classes' not in _options: _options['classes'] = []
# Try linking to the whole docs first
for basename, url, css_classes in tagfile_basenames:
if basename == target:
if not title:
# TODO: extract title from index page in the tagfile
logger.warning(
"Link to main page `{}` requires a title".format(target))
title = target
_options['classes'] += css_classes
node = nodes.reference(rawtext,
title,
refuri=url + hash,
**_options)
return [node], []
for prefix in symbol_prefixes:
if prefix + target in symbol_mapping:
link_title, url, css_classes = symbol_mapping[prefix + target]
if title:
use_title = title
elif link_title:
use_title = link_title
else:
if link_title is not None:
logger.warning(
"Doxygen anchor `{}` has no title, using its ID as link title"
.format(target))
use_title = target
_options['classes'] += css_classes
node = nodes.reference(rawtext,
use_title,
refuri=url + hash,
**_options)
return [node], []
# TODO: print file and line
#msg = inliner.reporter.warning(
#'Doxygen symbol %s not found' % target, line=lineno)
#prb = inliner.problematic(rawtext, rawtext, msg)
if title:
logger.warning(
"Doxygen symbol `{}` not found, rendering just link title".format(
target))
node = nodes.inline(rawtext, title, **_options)
else:
logger.warning(
"Doxygen symbol `{}` not found, rendering as monospace".format(
target))
node = nodes.literal(rawtext, target, **_options)
return [node], []
def run(self):
set_classes(self.options)
self.assert_has_content()
line_counts, lines = self.cleanup_content(
keep_slashes=self.options.has_key('keepslashes'))
text = '\n'.join(lines)
# Sending text to state machine for inline text replacement
text_nodes, messages = self.state.inline_text(text, self.lineno)
# Debugging Code start
# if messages:
# print "text:\n%s" % text
# print "text_nodes:\n%s" % text_nodes
# for n in text_nodes:
# print "n:\n%s" % n
# print 'messages:'
# for m in messages:
# print m
# Debugging Code end
node = TabbedParsedLiteralNode(text, '', *text_nodes, **self.options)
node.cleanup()
node.line = self.content_offset + 1
self.add_name(node)
node['copyable'] = self.options.has_key('copyable')
node['independent'] = self.options.has_key('independent')
node['languages'] = self.cleanup_options('languages',
DEFAULT_LANGUAGES)
node['line_counts'] = line_counts
node['linenos'] = self.cleanup_options('linenos', '')
node['single'] = self.options.has_key('single')
node['tab_labels'] = self.cleanup_options('tabs', DEFAULT_TAB_LABELS)
node['tabs'] = self.cleanup_options('tabs',
DEFAULT_TABS,
aphanumeric_only=True,
lower=True)
tab_count = len(node['tabs'])
if tab_count == 1:
# If only one tab, force to be independent
node['independent'] = True
# If languages were not supplied, make it a shell-session
if not self.options.has_key('languages'):
node['languages'] = [DEFAULT_LANGUAGES[1]]
if tab_count != len(node['languages']):
if self.options.get(
'languages', ''
): # If there was a 'languages' option, and we didn't just use the default:
print "Warning: number of tabs (%s) doesn't match number of languages (%s)" % (
node['tabs'], node['languages'])
print "Using '%s' for all tabs" % DEFAULT_LANGUAGES[0]
node['languages'] = [DEFAULT_LANGUAGES[0]] * tab_count
if not node['independent']:
node['dependent'] = self.cleanup_option('dependent',
DEFAULT_TAB_SET)
node['mapping'] = self.cleanup_options('mapping',
node['tabs'],
aphanumeric_only=True,
lower=True)
if tab_count != len(node['mapping']):
print "Warning: number of tabs (%s) doesn't match number of elements in the mapping (%s)" % (
node['tabs'], node['mapping'])
if tab_count > 1:
node['mapping'] = DEFAULT_TABS + [DEFAULT_TABS[0]
] * (tab_count - 2)
else:
node['mapping'] = [DEFAULT_TABS[0]] * tab_count
if tab_count > len(node['line_counts']):
print "Warning: number of tabs (%s) is greater than the number of elements in the line_counts (%s)" % (
node['tabs'], node['line_counts'])
return [node] + messages
def append_to_options_classes(options, role_name):
roles.set_classes(options)
if 'classes' not in options.keys():
options['classes'] = []
options['classes'].append('simp-%s' % role_name)
return (options)
def run(self):
set_classes(self.options)
node = role_video(source=self.arguments[0], **self.options)
return [node]
def sphinx_ref(options, rawtext, text, ref):
set_classes(options)
node = nodes.reference(rawtext, text, refuri=ref, **options)
return [node], []
def bookmark_role(role,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
"""``:bookmark:`<bookmark-eid>``` or ``:bookmark:`<eid>:<vid>```
Example: ``:bookmark:`1234:table```
Replace the directive with the output of applying the view to the resultset
returned by the query stored in the bookmark. By default, the view is the one
stored in the bookmark, but it can be overridden by the directive as in the
example above.
"X eid %(userid)s" can be used in the RQL query stored in the Bookmark, for
this query will be executed with the argument {'userid': _cw.user.eid}.
"""
_cw = inliner.document.settings.context._cw
text = text.strip()
try:
if ':' in text:
eid, vid = text.rsplit(u':', 1)
eid = int(eid)
else:
eid, vid = int(text), None
except ValueError:
msg = inliner.reporter.error(
'EID number must be a positive number; "%s" is invalid.' % text,
line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
try:
bookmark = _cw.entity_from_eid(eid)
except UnknownEid:
msg = inliner.reporter.error('Unknown EID %s.' % text, line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
try:
params = dict(_cw.url_parse_qsl(urlsplit(bookmark.path).query))
rql = params['rql']
if vid is None:
vid = params.get('vid')
except (ValueError, KeyError) as exc:
msg = inliner.reporter.error('Could not parse bookmark path %s [%s].' %
(bookmark.path, exc),
line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
try:
rset = _cw.execute(rql, {'userid': _cw.user.eid})
if rset:
if vid is None:
vid = vid_from_rset(_cw, rset, _cw.vreg.schema)
else:
vid = 'noresult'
view = _cw.vreg['views'].select(vid, _cw, rset=rset)
content = view.render()
except Exception as exc:
content = 'An error occurred while interpreting directive bookmark: %r' % exc
set_classes(options)
return [nodes.raw('', content, format='html')], []
def run(self):
set_classes(self.options)
rubric_text = self.arguments[0]
textnodes, messages = self.state.inline_text(rubric_text, self.lineno)
rubric = nodes.rubric(rubric_text, '', *textnodes, **self.options)
return [rubric] + messages
def issue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
ref = "https://github.com/scrapy/scrapy/issues/" + text
set_classes(options)
node = nodes.reference(rawtext, "issue " + text, refuri=ref, **options)
return [node], []
from pygments.lexers.web import PhpLexer
lexers['php'] = PhpLexer(startinline=True)
def github_link_node(name, rawtext, options=()):
try:
base = github_project_url
if not base:
raise AttributeError
except AttributeError, err:
raise ValueError(
'github_project_url configuration value is not set (%s)' % str(err))
slash = '/' if base[-1] != '/' else ''
ref = base + slash + rawtext
if not options:
options = {}
set_classes(options)
node = nodes.reference(name, utils.unescape(name), refuri=ref,
**options)
return node
# Return filename for example ex in the current language.
def xapian_code_example_filename(ex):
return "code/%s/%s%s" % (highlight_language, ex, ext)
# Return the command to show in the generated docs.
def xapian_code_example_command(ex):
if highlight_language == 'lua':
return "lua %s" % xapian_code_example_filename(ex)
elif highlight_language == 'perl':
return "perl %s" % xapian_code_example_filename(ex)
def metalabel_role(name,
rawtext,
text,
lineno,
inliner,
options={},
content=[]):
"""Meta-label role
Returns 2 part tuple containing list of nodes to insert into the
document and a list of system messages. Both are allowed to be
empty.
:param name: The role name used in the document.
:param rawtext: The entire markup snippet, with role.
:param text: The text marked with the role.
:param lineno: The line number where rawtext appears in the input.
:param inliner: The inliner instance that called us.
:param options: Directive options for customization.
:param content: The directive content for customization.
"""
try:
meta_labels = inliner.document.settings.env.app.config.meta_labels
assert isinstance(meta_labels, dict)
label_config = meta_labels.get(name)
assert isinstance(label_config, dict)
set_classes(options)
node = nodes.emphasis(rawtext='', text='', **options)
node['classes'].append('meta-label')
node1 = nodes.strong(raw=rawtext,
text=label_config.get('label', name),
**options)
node1['classes'].append('label')
node2 = nodes.emphasis(rawtext=rawtext, text=text, **options)
node += node1
node += node2
# Add information about the document meta labels to Spinx environment
env = inliner.document.settings.env
if not hasattr(env, "doc_metalabels"):
metalabel = dict()
metalabel[env.docname] = dict()
metalabel[env.docname][name] = [text]
setattr(env, "doc_metalabels", metalabel)
if env.docname not in env.doc_metalabels:
env.doc_metalabels[env.docname] = dict()
# Create a list if one metalabel have a lot of values (split by ',')
env.doc_metalabels[env.docname][name] = [
text.strip() for text in text.split(",")
]
except AssertionError:
msg = inliner.reporter.error('Cannot create meta-label "%s: %s". '
'Please check "meta_labels" in conf.py' %
(name, text),
line=lineno)
prb = inliner.problematic(rawtext, rawtext, msg)
return [prb], [msg]
return [
node,
], []
def ref(name, rawtext, text, lineno, inliner: Inliner, options={}, content=[]):
title, target, hash = parse_link(text)
# Otherwise adding classes to the options behaves globally (uh?)
_options = dict(options)
set_classes(_options)
# Avoid assert on adding to undefined member later
if 'classes' not in _options: _options['classes'] = []
# If we're in a page and there's no page module scope yet, look if there
# are :py:module: page metadata we could use for a prefix
global current_referer_path, page_ref_prefixes
if current_referer_path[-1][0].name == 'PAGE' and page_ref_prefixes is None:
# Since we're in the middle of parse, the nodes.docinfo is not present
# yet (it's produced by the frontmatter.DocInfo transform that's run
# after the parsing ends), so we look in field lists instead.
# TODO: DocInfo picks only the first ever field list happening right
# after a title and we should do the same to avoid picking up options
# later in the page. There the transform depends on DocTitle being
# ran already, so it would need to be more complex here. See
# docutils.transforms.frontmatter.DocInfo.apply() for details.
for docinfo in inliner.document.traverse(docutils.nodes.field_list):
for element in docinfo.children:
if element.tagname != 'field': continue
name_elem, body_elem = element.children
if name_elem.astext() == 'ref-prefix':
page_ref_prefixes = [
line.strip() + '.'
for line in body_elem.astext().splitlines()
if line.strip()
]
# If we didn't find any, set it to an empty list (not None), so this is
# not traversed again next time
if not page_ref_prefixes: page_ref_prefixes = []
# Add prefixes of the referer path to the global prefix list. Make an empty
# prefix first so :ref:`open()` always reliably links to the builtin
# instead whatever `foo.bar.open()` that's currently in scope. After that
# the names "closest" to the referer have the biggest priority with shorter
# referer_path prefixes after, and name prefixes from M_SPHINX_INVENTORIES
# last.
global intersphinx_inventory, intersphinx_name_prefixes
referer_path = current_referer_path[-1][1] if current_referer_path else []
prefixes = [''] + [
'.'.join(referer_path[:len(referer_path) - i]) + '.'
for i, _ in enumerate(referer_path)
] + (page_ref_prefixes
if page_ref_prefixes else []) + intersphinx_name_prefixes
for prefix in prefixes:
found = None
# If the target is prefixed with a type, try looking up that type
# directly. The implicit link title is then without the type.
m = _type_prefix_re.match(target)
if m:
type = m.group(1)
prefixed = prefix + target[len(type) + 1:]
# ALlow trailing () on functions here as well
if prefixed.endswith('()') and type in _function_types:
prefixed = prefixed[:-2]
if type in intersphinx_inventory and prefixed in intersphinx_inventory[
type]:
target = target[len(type) + 1:]
found = type, intersphinx_inventory[m.group(1)][prefixed]
prefixed = prefix + target
# If the target looks like a function, look only in functions and strip
# the trailing () as the inventory doesn't have that
if not found and prefixed.endswith('()'):
prefixed = prefixed[:-2]
for type in _function_types:
if type in intersphinx_inventory and prefixed in intersphinx_inventory[
type]:
found = type, intersphinx_inventory[type][prefixed]
break
# Iterate through whitelisted types otherwise. Skipping
# 'std:pdbcommand', 'std:cmdoption', 'std:term', 'std:label',
# 'std:opcode', 'std:envvar', 'std:token', 'std:doc', 'std:2to3fixer'
# and unknown domains such as c++ for now as I'm unsure about potential
# name clashes.
if not found:
for type in [
'py:exception',
'py:attribute',
'py:method',
'py:data',
'py:module',
'py:function',
'py:class',
'py:classmethod',
'py:staticmethod',
'c:var',
'c:type',
'c:function',
'c:member',
'c:macro',
# TODO: those apparently don't exist:
'py:enum',
'py:enumvalue'
]:
if type in intersphinx_inventory and prefixed in intersphinx_inventory[
type]:
found = type, intersphinx_inventory[type][prefixed]
if found:
url, link_title, css_classes = found[1]
if title:
use_title = title
elif link_title != '-':
use_title = link_title
else:
use_title = target
# Add () to function refs
if found[0] in _function_types and not target.endswith('()'):
use_title += '()'
_options['classes'] += css_classes
node = nodes.reference(rawtext,
use_title,
refuri=url + hash,
**_options)
return [node], []
if title:
logging.warning(
"Sphinx symbol `{}` not found, rendering just link title".format(
target))
node = nodes.inline(rawtext, title, **_options)
else:
logging.warning(
"Sphinx symbol `{}` not found, rendering as monospace".format(
target))
node = nodes.literal(rawtext, target, **_options)
return [node], []
def commit_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
ref = REPO + 'commit/' + text
set_classes(options)
node = nodes.reference(rawtext, text, refuri=ref, **options)
return [node], []
def run(self):
"""Run code block directive."""
self.assert_has_content()
if 'linenos' in self.options:
self.options['number-lines'] = self.options['linenos']
if 'tab-width' in self.options:
self.content = [
x.replace('\t', ' ' * self.options['tab-width'])
for x in self.content
]
if self.arguments:
language = self.arguments[0]
else:
language = 'text'
set_classes(self.options)
classes = ['code']
if language:
classes.append(language)
if 'classes' in self.options:
classes.extend(self.options['classes'])
code = '\n'.join(self.content)
try:
lexer = get_lexer_by_name(language)
except pygments.util.ClassNotFound:
raise self.error(
'Cannot find pygments lexer for language "{0}"'.format(
language))
if 'number-lines' in self.options:
linenos = 'table'
# optional argument `startline`, defaults to 1
try:
linenostart = int(self.options['number-lines'] or 1)
except ValueError:
raise self.error(':number-lines: with non-integer start value')
else:
linenos = False
linenostart = 1 # actually unused
if self.site.invariant: # for testing purposes
anchor_ref = 'rest_code_' + 'fixedvaluethatisnotauuid'
else:
anchor_ref = 'rest_code_' + uuid.uuid4().hex
formatter = utils.NikolaPygmentsHTML(anchor_ref=anchor_ref,
classes=classes,
linenos=linenos,
linenostart=linenostart)
out = pygments.highlight(code, lexer, formatter)
node = nodes.raw('', out, format='html')
self.add_name(node)
# if called from "include", set the source
if 'source' in self.options:
node.attributes['source'] = self.options['source']
return [node]
def run(self):
if 'align' in self.options:
if isinstance(self.state, states.SubstitutionDef):
# Check for align_v_values.
if self.options['align'] not in self.align_v_values:
raise self.error(
'Error in "%s" directive: "%s" is not a valid value '
'for the "align" option within a substitution '
'definition. Valid values for "align" are: "%s".' %
(self.name, self.options['align'], '", "'.join(
self.align_v_values)))
elif self.options['align'] not in self.align_h_values:
raise self.error(
'Error in "%s" directive: "%s" is not a valid value for '
'the "align" option. Valid values for "align" are: "%s".'
% (self.name, self.options['align'], '", "'.join(
self.align_h_values)))
messages = []
# previous code from Image.run()
# --------------------------------------------------------------------
sumatra_options = build_options(self.state.document.settings,
self.options)
# determine which record store to use
prj = determine_project(sumatra_options)
record_store = determine_record_store(prj, sumatra_options, self.error)
# determine the project (short) name
project_name = determine_project_name(prj, sumatra_options, self.error)
record_label, image_path = get_record_label_and_image_path(
self.arguments[0])
record = record_store.get(project_name, record_label)
image = get_image(record, image_path, self.options,
self.error) # automatically checks digest
if hasattr(image, "url"):
reference = image.url
else:
if not os.path.exists(LOCAL_IMAGE_CACHE):
os.makedirs(LOCAL_IMAGE_CACHE)
reference = image.save_copy(LOCAL_IMAGE_CACHE)
# set values for alt and target, if they have not been specified
if not 'target' in self.options and hasattr(record_store,
'server_url'):
self.options['target'] = record_link_url(record_store.server_url,
project_name,
record_label)
if not 'alt' in self.options:
self.options[
'alt'] = "Data file generated by computation %s" % record_label
# --------------------------------------------------------------------
# following code from Image.run()
self.options['uri'] = reference
reference_node = None
if 'target' in self.options:
block = states.escape2null(self.options['target']).splitlines()
block = [line for line in block]
target_type, data = self.state.parse_target(
block, self.block_text, self.lineno)
if target_type == 'refuri':
reference_node = nodes.reference(refuri=data)
elif target_type == 'refname':
reference_node = nodes.reference(
refname=fully_normalize_name(data),
name=whitespace_normalize_name(data))
reference_node.indirect_reference_name = data
self.state.document.note_refname(reference_node)
else: # malformed target
messages.append(data) # data is a system message
del self.options['target']
set_classes(self.options)
image_node = nodes.image(self.block_text, **self.options)
self.add_name(image_node)
if reference_node:
reference_node += image_node
return messages + [reference_node]
else:
return messages + [image_node]
def source_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
ref = REPO + 'blob/master/' + text
set_classes(options)
node = nodes.reference(rawtext, text, refuri=ref, **options)
return [node], []
def run(self):
""" build rv_code node """
set_classes(self.options)
self.assert_has_content()
node = self.node_class('\n'.join(self.content), **self.options)
return [node]
def gh_role(name, rawtext, pr_number, lineno, inliner, options={}, content=[]):
"""Link to a GitHub pull request."""
ref = f'https://github.com/benchopt/benchOpt/pull/{pr_number}'
set_classes(options)
node = reference(rawtext, '#' + pr_number, refuri=ref, **options)
return [node], []
def rev_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
ref = 'http://hg.scrapy.org/scrapy/changeset/' + text
set_classes(options)
node = nodes.reference(rawtext, 'r' + text, refuri=ref, **options)
return [node], []
def run(self):
extension_list_name = self.options.pop('list', '')
set_classes(self.options)
admonition_node = nodes.admonition('', **self.options)
self.add_name(admonition_node)
title_text = self.arguments[0]
textnodes, _ = self.state.inline_text(title_text, self.lineno)
title = nodes.title(title_text, '', *textnodes)
title.line = 0
title.source = 'extension_list_' + extension_list_name
admonition_node += title
if not 'classes' in self.options:
admonition_node['classes'] += ['admonition', 'note']
admonition_node['classes'] += ['extension_list']
admonition_node['ids'] += ['extensionlist-' + extension_list_name]
definition_list = nodes.definition_list()
definition_list.line = 0
for num, extension in enumerate(extension_json['extensions']):
if not extension.get('core'):
continue
category = extension.get('category')
if extension_list_name and category != extension_list_name:
continue
name = extension['name']['en']
description = extension['description']['en']
some_term, _ = self.state.inline_text(name, self.lineno)
some_def, _ = self.state.inline_text(description, self.lineno)
link = nodes.reference(name, '', *some_term)
path_split = self.state.document.attributes['source'].split('/')
root_path = "../" * (len(path_split) - path_split.index('docs') -
2)
link['refuri'] = root_path + 'extensions/' + extension.get(
'slug', '')
link['translatable'] = True
link.source = 'extension_list_' + extension_list_name
link.line = num + 1
term = nodes.term(name, '', link)
definition_list += term
text = nodes.paragraph(description, '', *some_def)
text.source = 'extension_list_' + extension_list_name
text.line = num + 1
definition_list += nodes.definition(description, text)
admonition_node += definition_list
community = "The following are community extensions and are not maintained by Open Contracting Partnership."
community_text, _ = self.state.inline_text(community, self.lineno)
community_paragraph = nodes.paragraph(community, *community_text)
community_paragraph['classes'] += ['hide']
community_paragraph.source = 'extension_list_' + extension_list_name
community_paragraph.line = num + 2
admonition_node += community_paragraph
return [admonition_node]
def notest_role(role, rawtext, text, lineno, inliner, options={}, content=[]):
roles.set_classes(options)
i = rawtext.find('`')
text = rawtext.split('`')[1]
node = notest(rawtext, text, **options)
return [node], []
def issue_role(name, rawtext, text, lineno, inliner, options={}, content=[]):
ref = 'https://github.com/pulse2percept/pulse2percept/issues/' + text
set_classes(options)
node = nodes.reference(rawtext, 'issue #' + text, refuri=ref, **options)
return [node], []
