def handle_signature(self, sig, signode, display_text=None):
"""This method determines the appearance of the object.
Overloaded Args:
display_test: Used for overriding the object name.
"""
# Override sig with display_text if provided.
if display_text is None:
display_text = sig
display_text, argument, alt_forms = self.process_name(display_text)
# Add a label before the name of the object.
signode += addnodes.desc_annotation(*('%s ' % self.LABEL,) * 2)
# Add the object name.
signode += addnodes.desc_name(sig, display_text)
# Add arguments.
if argument:
argument = '%s %s' % (self.ARGUMENT_SEPARATOR, argument)
signode += addnodes.desc_annotation(argument, argument)
# Add alternate object names.
if alt_forms:
signode += addnodes.desc_annotation(
*(self.ALT_FORM_TEMPLATE % (', '.join(alt_forms)),) * 2)
signode['fullname'] = sig
return (sig, self.NAME, sig)
def handle_signature(self, sig: str, signode: addnodes.desc) -> str:
"""Transform signature into RST nodes"""
signode += addnodes.desc_annotation(self.typename, self.typename + " ")
signode += addnodes.desc_name(sig, sig)
if 'badges' in self.options:
badges = addnodes.desc_annotation()
badges['classes'] += ['badges']
content = StringList([self.options['badges']])
self.state.nested_parse(content, 0, badges)
signode += badges
if 'replaces_section_title' in self.options:
section = self.state.parent
if isinstance(section, nodes.section):
title = section[-1]
if isinstance(title, nodes.title):
section.remove(title)
else:
signode += self.state.document.reporter.warning(
"%s:%s:: must follow section directly to replace section title"
% (self.domain, self.objtype), line = self.lineno
)
else:
signode += self.state.document.reporter.warning(
"%s:%s:: must be in section to replace section title"
% (self.domain, self.objtype), line = self.lineno
)
return sig
def handle_signature(self, sig, signode):
#synopsis = unicodedata.normalize('NFD', self.options.get('synopsis'))
synopsis = self.options.get('synopsis')
module = self.env.temp_data.get('nscp:module')
fullname = 'TODO'
if self.objtype == 'query':
fullname = '%s.%s'%(module, sig)
signode['fullname'] = fullname
signode += addnodes.desc_addname(module, module)
signode += addnodes.desc_name(sig, sig)
signode += addnodes.desc_content('')
signode += addnodes.compact_paragraph(synopsis, synopsis)
elif self.objtype == 'option':
command = self.env.temp_data.get('nscp:command')
fullname = '%s.%s:%s'%(module, command, sig)
signode['fullname'] = fullname
ann = ' (%s, %s)'%(module, command)
signode += addnodes.desc_name(sig, sig)
signode += addnodes.desc_annotation(ann, ann)
elif self.objtype == 'confpath':
fullname = '%s:%s'%(module, sig)
signode['fullname'] = fullname
ann = ' (%s)'%(module)
signode += addnodes.desc_name(sig, sig)
signode += addnodes.desc_annotation(ann, ann)
elif self.objtype == 'confkey':
confpath = self.env.temp_data.get('nscp:confpath', '')
fullname = '%s:%s:%s'%(module, confpath, sig)
signode['fullname'] = fullname
ann = ' (%s, %s)'%(module, confpath)
signode += addnodes.desc_name(sig, sig)
signode += addnodes.desc_annotation(ann, ann)
#print 'handle_signature(%s, %s) => %s'%(sig, signode, fullname)
return fullname, sig
def handle_signature(self, sig, signode):
context, name, argstart, arglist, argend, retann = self.parse_signature(sig)
self.context, self.contextsep = self.build_context(context)
self.module = self.options.get('module', self.env.temp_data.get('haka:module'))
self.objtype = self.build_objtype()
self.idxtype = self.options.get('idxtype') or self.options.get('objtype')
self.name = name
self.argstart = argstart
self.arglist = arglist
self.argend = argend
self.retann = retann
add_module = True
fullname = name
signode['module'] = self.module
signode['class'] = self.context
signode['fullname'] = fullname
prefix = "%s " % (self.objtype)
signode += addnodes.desc_annotation(prefix, prefix)
if self.module and self.needs_module():
modname = '%s.' % (self.module)
signode += addnodes.desc_addname(modname, modname)
self.build_signode(signode)
anno = self.options.get('annotation')
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return {'fullname': fullname, 'context': self.context,
'objtype': self.objtype, 'idxctx': self.options.get('idxctx') or ""}
def handle_signature(self, sig, signode):
"""Handle IDL signature lines"""
m = idl_sig_re.match(sig)
if not m:
self.env.app.warn("Signature did not match for {}".format(sig))
raise ValueError("Signature did not match!")
pro_or_function, name, arglist = m.groups()
# Add a prefix for function/program
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
signode += addnodes.desc_annotation(self.objtype, self.objtype)
# Register the full name of the program
signode['fullname'] = name
signode += addnodes.desc_name(name, name)
# Parse the argument list from the signature
if not arglist and self.objtype == 'function':
signode += addnodes.desc_parameterlist()
elif arglist:
_pseudo_parse_arglist(signode, arglist)
return (name, '')
def attach_modifiers(self, node, obj):
if obj.visibility != 'public':
node += addnodes.desc_annotation(obj.visibility,
obj.visibility)
node += nodes.Text(' ')
if obj.static:
node += addnodes.desc_annotation('static', 'static')
node += nodes.Text(' ')
def handle_signature(self, sig, signode):
a = (context, name, argstart, arglist, argend, retann) = self.parse_signature(sig)
self.context, self.contextsep = self.build_context(context)
self.module = self.options.get('module', self.env.temp_data.get('lua:module'))
self.clsname = self.options.get('class', self.env.temp_data.get('lua:class'))
self.objtype = self.build_objtype()
self.idxtype = self.options.get('idxtype') or self.options.get('objtype')
self.name = name
self.argstart = argstart
self.arglist = arglist
self.argend = argend
self.retann = retann
# print "context: '%s', name: '%s'" % a[:2]
# print "module: '%s', clsname: '%s', idxtype: '%s'" % (self.module, self.clsname, self.idxtype)
# print "typename: '%s', objtype: '%s'" % (self.typename, self.objtype)
# print "needs_module: '%s', needs_class: '%s'" % (self.needs_class(), self.needs_module())
# print ""
add_module = True
fullname = name
signode['module'] = self.module
signode['class'] = self.context
signode['fullname'] = fullname
prefix = "%s " % (self.objtype)
signode += addnodes.desc_annotation(prefix, prefix)
clsname = ''
if fullname.find('.') != -1 or str(self.typename) == "object":
pass
elif self.clsname and self.needs_class():
sprtr = '.' if str(self.typename) == "data" else ':'
clsname = '%s%s' % (self.clsname, sprtr)
elif self.module and self.needs_module():
clsname = '%s.' % (self.module)
if clsname:
signode += addnodes.desc_addname(clsname, clsname)
# if self.clsname and self.needs_class():
# signode += addnodes.desc_addname(clsname, clsname)
# elif str(self.typename) == "data":
# clsname = '%s:' % (self.clsname)
# signode += addnodes.desc_addname(clsname, clsname)
# elif self.module and self.needs_module():
# modname = '%s.' % (self.module)
# signode += addnodes.desc_addname(modname, modname)
self.build_signode(signode)
anno = self.options.get('annotation')
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return {'fullname': fullname, 'context': self.context,
'objtype': self.objtype, 'idxctx': self.options.get('idxctx') or ""}
def handle_signature(self, sig_input, signode):
"""Parses out pieces from construct signatures
Parses out prefix and argument list from construct definition. This is
assuming that the .NET languages this will support will be in a common
format, such as::
Namespace.Class.method(argument, argument, ...)
The namespace and class will be determined by the nesting of rST
directives.
Returns
Altered :py:data:`signode` with attributes corrected for rST
nesting/etc
"""
try:
sig = self.parse_signature(sig_input.strip())
except ValueError:
self.env.warn(self.env.docname,
'Parsing signature failed: "{}"'.format(sig_input),
self.lineno)
raise
prefix = self.env.ref_context.get('dn:prefix', None)
if prefix is not None:
sig.prefix = prefix
signode['object'] = sig.member
signode['prefix'] = sig.prefix
signode['fullname'] = sig.full_name()
# Prefix modifiers
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
for prefix in ['public', 'protected', 'static']:
if prefix in self.options:
signode += addnodes.desc_annotation(prefix + ' ',
prefix + ' ')
# Show prefix only on shorter declarations
if sig.prefix is not None and not self.has_arguments:
signode += addnodes.desc_addname(sig.prefix + '.', sig.prefix + '.')
signode += addnodes.desc_name(sig.member, sig.member)
if self.has_arguments:
if not sig.arguments:
signode += addnodes.desc_parameterlist()
else:
# TODO replace this
_pseudo_parse_arglist(signode, ', '.join(sig.arguments))
if isinstance(self, DotNetObjectNested):
return sig.full_name(), sig.full_name()
return sig.full_name(), sig.prefix
def attach_modifiers(self, node, obj, visibility="public"):
if obj.visibility != visibility:
node += addnodes.desc_annotation(obj.visibility, obj.visibility)
node += nodes.Text(" ")
if obj.static:
node += addnodes.desc_annotation("static", "static")
node += nodes.Text(" ")
if getattr(obj, "constexpr", False):
node += addnodes.desc_annotation("constexpr", "constexpr")
node += nodes.Text(" ")
def p_returnval_expr(p): '''returnval : MINUS LPAREN expression RPAREN | PLUS LPAREN expression RPAREN''' p[0] = addnodes.desc_annotation(p[1], p[1]) p[0] += nodes.Text(u' ') p[0] += addnodes.desc_annotation(p[2], p[2]) p[0] += nodes.Text(u' ') p[0] += p[3] p[0] += nodes.Text(u' ') p[0] += addnodes.desc_annotation(p[4], p[4])
def attach_modifiers(self, node, obj):
lname = self.__class__.langname
node += nodes.strong(lname + ":", lname + ":")
node += addnodes.desc_name(" ", " ")
if obj.visibility != 'public':
node += addnodes.desc_annotation(obj.visibility,
obj.visibility)
node += nodes.Text(' ')
if obj.static:
node += addnodes.desc_annotation('static', 'static')
node += nodes.Text(' ')
def attach_modifiers(self, node, obj, visibility='public'):
if obj.visibility != visibility:
node += addnodes.desc_annotation(obj.visibility,
obj.visibility)
node += nodes.Text(' ')
if obj.static:
node += addnodes.desc_annotation('static', 'static')
node += nodes.Text(' ')
if getattr(obj, 'constexpr', False):
node += addnodes.desc_annotation('constexpr', 'constexpr')
node += nodes.Text(' ')
def p_parameters_exp(p): '''parameters : LPAREN expression RPAREN methodname | LPAREN expression RPAREN methodname parameter''' p[0] = addnodes.desc_annotation(p[1], p[1]) p[0] += nodes.Text(u' ') p[0] += p[2] p[0] += nodes.Text(u' ') p[0] += addnodes.desc_annotation(p[3], p[3]) p[0] += p[4] if (len(p) == 6): p[0] += nodes.Text(u' ') p[0] += p[5]
def handle_signature(self, sig, signode):
"""Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
name_prefix = None
name = sig
arglist = None
retann = None
# determine module and class name (if applicable), as well as full name
modname = self.options.get(
'module', self.env.temp_data.get('py:module'))
classname = self.env.temp_data.get('py:class')
fullname = name
signode['module'] = modname
signode['class'] = classname
signode['fullname'] = fullname
sig_prefix = self.get_signature_prefix(sig)
if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if name_prefix:
signode += addnodes.desc_addname(name_prefix, name_prefix)
anno = self.options.get('annotation')
signode += addnodes.desc_name(name, name)
if not arglist:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, name_prefix
_pseudo_parse_arglist(signode, arglist)
if retann:
signode += addnodes.desc_returns(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, name_prefix
def handle_signature(self, sig, signode):
match = re.search('(\w+)', sig)
name = match.groups()[0]
# At this point, we make no attempt to break up the arglist into
# reqired parameters, keywords, optional arguments etc.
# This would be very hard, since we would have to cover the syntax
# of shell, IDL, S-Lang, ...
# For our output all we want is to attach it to the name in
# reasonable formatting.
arglist = sig[len(name):]
anno = self.options.get('annotation')
lang = self.options.get('language')
signode += addnodes.desc_name(name, name)
# addname has a good formatting, even if it is meant for a
# different use in sphinx for python.
# Sphinx expects name + parameterlist, but unfortunately,
# the parameterlist is automatically wrapped in (), so we avoid that
# here.
signode += addnodes.desc_addname(arglist, arglist)
if lang:
signode += addnodes.desc(' ' + lang, ' ' + lang)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return name
def handle_signature(self, sig, signode):
method = self.method.upper() + " "
signode += addnodes.desc_name(method, method)
offset = 0
path = None
for match in http_sig_param_re.finditer(sig):
path = sig[offset : match.start()]
signode += addnodes.desc_name(path, path)
params = addnodes.desc_parameterlist()
typ = match.group("type")
if typ:
typ += ": "
params += addnodes.desc_annotation(typ, typ)
name = match.group("name")
params += addnodes.desc_parameter(name, name)
signode += params
offset = match.end()
if offset < len(sig):
path = sig[offset : len(sig)]
signode += addnodes.desc_name(path, path)
if path is None:
assert False, "no matches for sig: %s" % sig
fullname = self.method.upper() + " " + path
signode["method"] = self.method
signode["path"] = sig
signode["fullname"] = fullname
return (fullname, self.method, sig)
def handle_signature(self, sig, signode):
sdkname = self.options.get('sdk', self.env.ref_context.get('qbs:sdk'))
pkgname = self.options.get('package', self.env.ref_context.get('qbs:package'))
modname = self.env.ref_context.get('qbs:module', None)
itemname = self.env.ref_context.get('qbs:item', None)
type, name, value = self.parse(sig)
signode['module'] = modname
signode['package'] = pkgname
signode['item'] = itemname
if self.objtype == 'property':
fullname = self.get_signature_name(objname=(modname or itemname), name=name)
else:
fullname = name
signode['sdk'] = sdkname
signode['fullname'] = fullname
sigprefix = self.get_signature_prefix()
if sigprefix:
signode += addnodes.desc_annotation(sigprefix, sigprefix)
if type:
signode += addnodes.desc_addname(type, type)
if name:
signode += addnodes.desc_name(name, name)
if value:
signode += addnodes.desc_returns(value, value)
return fullname
def handle_signature(self, signature, signode):
"""Handle the given ``signature``.
In addition to the normal signature handling of the
:class:`EmacsLispSymbol` directive, parse and annotate the function
signature of the symbol.
"""
parts = signature.split(' ')
name = parts[0]
arguments = parts[1:]
name = EmacsLispSymbol.handle_signature(self, name, signode)
paramlist = nodes.el_parameterlist(' '.join(arguments), '')
signode += paramlist
for arg in arguments:
if arg.startswith('&'):
paramlist += addnodes.desc_annotation(' ' + arg + ' ',
' ' + arg + ' ')
else:
node = nodes.el_parameter(arg, arg)
node['noemph'] = True
paramlist += node
return name
def describe_signature(self, signode, obj):
self.attach_modifiers(signode, obj)
signode += addnodes.desc_annotation('type ', 'type ')
if obj.typename is not None:
self.attach_type(signode, obj.typename)
signode += nodes.Text(' ')
self.attach_name(signode, obj.name)
def handle_signature(self, sig, signode):
method = self.method.upper() + ' '
signode += addnodes.desc_name(method, method)
offset = 0
path = None
for match in http_sig_param_re.finditer(sig):
path = sig[offset:match.start()]
signode += addnodes.desc_name(path, path)
params = addnodes.desc_parameterlist()
typ = match.group('type')
if typ:
typ += ': '
params += addnodes.desc_annotation(typ, typ)
name = match.group('name')
params += addnodes.desc_parameter(name, name)
signode += params
offset = match.end()
if offset < len(sig):
path = sig[offset:len(sig)]
signode += addnodes.desc_name(path, path)
assert path is not None, 'no matches for sig: %s' % sig
fullname = self.method.upper() + ' ' + path
signode['method'] = self.method
signode['path'] = sig
signode['fullname'] = fullname
return (fullname, self.method, sig)
def _pseudo_parse_arglist(signode, arglist):
""""Parse" a list of arguments separated by commas.
Arguments can have "optional" annotations given by enclosing them in
brackets. Currently, this will split at any comma, even if it's inside a
string literal (e.g. default argument value).
"""
paramlist = desc_parameterlist()
stack = [paramlist]
try:
for argument in arglist.split(' '):
argument = argument.strip()
ends_open = ends_close = 0
while argument.startswith('['):
stack.append(addnodes.desc_optional())
stack[-2] += stack[-1]
argument = argument[1:].strip()
while argument.startswith(']'):
stack.pop()
argument = argument[1:].strip()
while argument.endswith(']'):
ends_close += 1
argument = argument[:-1].strip()
while argument.endswith('['):
ends_open += 1
argument = argument[:-1].strip()
if argument:
stack[-1] += addnodes.desc_parameter(argument, argument)
while ends_open:
stack.append(addnodes.desc_optional())
stack[-2] += stack[-1]
ends_open -= 1
while ends_close:
stack.pop()
ends_close -= 1
if len(stack) != 1:
raise IndexError
except IndexError:
# if there are too few or too many elements on the stack, just give up
# and treat the whole argument list as one argument, discarding the
# already partially populated paramlist node
signode += addnodes.desc_annotation(' ', ' ')
signode += desc_parameterlist()
signode[-1] += addnodes.desc_parameter(arglist, arglist)
else:
signode += addnodes.desc_annotation(' ', ' ')
signode += paramlist
def handle_signature(self, sig, signode):
sig = sig.strip()
if '(' in sig and sig[-1:] == ')':
prefix, arglist = sig.split('(', 1)
prefix = prefix.strip()
arglist = arglist[:-1].strip()
else:
prefix = sig
arglist = None
if '.' in prefix:
nameprefix, name = prefix.rsplit('.', 1)
else:
nameprefix = None
name = prefix
objectname = self.env.temp_data.get('js:object')
if nameprefix:
if objectname:
# someone documenting the method of an attribute
# of the current object? shouldn't happen but
# who knows...
nameprefix = objectname + '.' + nameprefix
fullname = nameprefix + '.' + name
elif objectname:
fullname = objectname + '.' + name
else:
# just a function or constructor
objectname = ''
fullname = name
signode['object'] = objectname
signode['fullname'] = fullname
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
if nameprefix:
signode += addnodes.desc_addname(nameprefix + '.',
nameprefix + '.')
signode += addnodes.desc_name(name, name)
if self.has_arguments:
if not arglist:
signode += addnodes.desc_parameterlist()
else:
_pseudo_parse_arglist(signode, arglist)
class_name = self.options.get('outertype')
# object belongs to some class or namespace
if class_name:
# func_desc = function return type + function name
func_desc = fullname.split(' ', 1)
if len(func_desc) > 1:
fullname = func_desc[0] + ' ' + class_name +\
'.' + func_desc[1]
return fullname, nameprefix
def envy_resolve(app, doctree, fromdocname):
objects = app.env.domaindata['envy']['objects']
# add uplink info
for holder in doctree.traverse(uplink_placeholder):
obj = objects[holder.name]
links = []
for sp, pos, name, variants in obj.uplinks:
signode = addnodes.desc_signature('', '')
signode['first'] = False
signode += make_refnode(app.builder, fromdocname, sp.docname, sp.iname + '-' + sp.name, addnodes.desc_addname(sp.name, sp.name), sp.name)
text = ' {}: {}'.format(pos, name)
signode += addnodes.desc_name(text, text)
if variants is not None:
text = ' [{}]'.format(variants)
signode += addnodes.desc_annotation(text, text)
links.append(signode)
holder.replace_self(links)
# add subnode list
for holder in doctree.traverse(sub_placeholder):
obj = objects[holder.name]
add_variant = False
for pos, name, child, variants in obj.subs:
if variants is not None:
add_variant = True
table = nodes.table()
headers = [(1, 'Address'), (1, 'Name'), (10, 'Description')]
if add_variant:
headers.insert(1, (1, 'Variants'))
tgroup = nodes.tgroup(cols=len(headers))
table += tgroup
for colwidth, header in headers:
tgroup += nodes.colspec(colwidth=colwidth)
thead = nodes.thead()
tgroup += thead
headrow = nodes.row()
for colwidth, header in headers:
entry = nodes.entry()
para = nodes.paragraph()
entry += para
para += nodes.Text(header, header)
headrow += entry
thead += headrow
tbody = nodes.tbody()
tgroup += tbody
for pos, name, child, variants in obj.subs:
row = nodes.row()
row += wrap_text_entry(pos)
if add_variant:
row += wrap_text_entry('all' if variants is None else variants)
row += wrap_text_entry(name)
entry = nodes.entry()
para = nodes.paragraph()
entry += para
para += make_refnode(app.builder, fromdocname, child.docname, child.iname + '-' + child.name, nodes.Text(child.brief, child.brief), obj.brief)
row += entry
tbody += row
holder.replace_self([table])
def handle_signature(self, sig, signode):
# add prefix like 'traversal' or 'lookup'
if self.desc_annotation:
prefix = '[%s] ' % self.desc_annotation
signode += addnodes.desc_annotation(prefix, prefix)
name = sig.split('(')[0]
signode += addnodes.desc_name(sig, sig)
return name
def describe_signature(self, signode, obj):
self.attach_modifiers(signode, obj)
signode += addnodes.desc_annotation("type ", "type ")
if obj.typename is not None:
self.attach_type(signode, obj.typename)
signode += nodes.Text(" ")
self.attach_name(signode, obj.name)
self.attach_type_suffixes(signode, obj.type_suffixes)
def handle_signature(self, sig, signode):
if ':' not in sig:
return PyClassmember.handle_signature(self, sig, signode)
name, descr = sig.split(':')
name = name.strip()
fullname, prefix = PyClassmember.handle_signature(self, name, signode)
descr = ' (' + descr.strip() + ')'
signode += addnodes.desc_annotation(descr, descr)
return fullname, prefix
def p_parameter_exp(p): '''parameter : methodname COLON LPAREN expression RPAREN methodname | parameter parameter''' if (len(p) == 7): p[0] = p[1] p[0] += addnodes.desc_annotation(p[2], p[2]) p[0] += addnodes.desc_annotation(p[3], p[3]) p[0] += nodes.Text(u' ') p[0] += p[4] p[0] += nodes.Text(u' ') p[0] += addnodes.desc_annotation(p[5], p[5]) p[0] += p[6] else: p[0] = p[1] p[0] += nodes.Text(u' ') p[0] += p[2]
def handle_signature(self, sig, signode):
sig = sig.strip()
if '(' in sig and sig[-1:] == ')':
prefix, arglist = sig.split('(', 1)
prefix = prefix.strip()
arglist = arglist[:-1].strip()
else:
prefix = sig
arglist = None
if '.' in prefix:
nameprefix, name = prefix.rsplit('.', 1)
else:
nameprefix = None
name = prefix
objectname = self.env.temp_data.get('mongodb:object')
if nameprefix:
if objectname:
# someone documenting the method of an attribute of the current
# object? shouldn't happen but who knows...
nameprefix = objectname + '.' + nameprefix
fullname = nameprefix + '.' + name
elif objectname:
fullname = objectname + '.' + name
else:
# just a function or constructor
objectname = ''
fullname = name
signode['object'] = objectname
signode['fullname'] = fullname
if self.display_prefix:
signode += addnodes.desc_annotation(self.display_prefix,
self.display_prefix)
if nameprefix:
if nameprefix in conf['suppress-prefix']:
pass
else:
nameprefix += '.'
for prefix in conf['suppress-prefix']:
if nameprefix.startswith(prefix):
nameprefix = nameprefix[len(prefix)+1:]
break
signode += addnodes.desc_addname(nameprefix, nameprefix)
nameprefix[:-1]
signode += addnodes.desc_name(name, name)
if self.has_arguments:
if not arglist:
signode += addnodes.desc_parameterlist()
else:
_pseudo_parse_arglist(signode, arglist)
return fullname, nameprefix
def run(self):
self.env = env = self.state.document.settings.env
# normalize whitespace in fullname like XRefRole does
fullname = ws_re.sub(' ', self.arguments[0].strip())
targetname = '%s-%s' % (self.ref_type, fullname)
# keep the target; this may be used to generate a BBIndex later
targets = env.domaindata['bb']['targets'].setdefault(self.ref_type, {})
targets[fullname] = env.docname, targetname
# make up the descriptor: a target and potentially an index descriptor
node = nodes.target('', '', ids=[targetname])
ret = [node]
# add the target to the document
self.state.document.note_explicit_target(node)
# append the index node if necessary
entries = []
for tpl in self.indextemplates:
colon = tpl.find(':')
if colon != -1:
indextype = tpl[:colon].strip()
indexentry = tpl[colon + 1:].strip() % (fullname,)
else:
indextype = 'single'
indexentry = tpl % (fullname,)
entries.append(
(indextype, indexentry, targetname, targetname, None))
if entries:
inode = addnodes.index(entries=entries)
ret.insert(0, inode)
# if the node has content, set up a signature and parse the content
if self.has_content:
descnode = addnodes.desc()
descnode['domain'] = 'bb'
descnode['objtype'] = self.ref_type
descnode['noindex'] = True
signode = addnodes.desc_signature(fullname, '')
if self.name_annotation:
annotation = "%s " % self.name_annotation
signode += addnodes.desc_annotation(annotation, annotation)
signode += addnodes.desc_name(fullname, fullname)
descnode += signode
contentnode = addnodes.desc_content()
self.state.nested_parse(self.content, 0, contentnode)
DocFieldTransformer(self).transform_all(contentnode)
descnode += contentnode
ret.append(descnode)
return ret
def handle_signature(self, sig, signode):
m = plsql_sig_re.match(sig)
if m is None:
raise ValueError
name_prefix, name, arglist, retann = m.groups()
if not name_prefix:
name_prefix = ''
if self.env.temp_data.get('plsql:in_package'):
name_prefix = self.env.temp_data['plsql:current_package'] + '.'
sig_prefix = self.get_signature_prefix(sig)
if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if not self.env.temp_data.get('plsql:in_package'):
signode += addnodes.desc_annotation(name_prefix, name_prefix)
fullname = ''
if name_prefix:
fullname += name_prefix
fullname += name
signode += addnodes.desc_name(name, name)
if arglist:
signode += addnodes.desc_parameterlist()
stack = [signode[-1]]
for token in arglist.split(','):
if not token or token == ',' or token.isspace():
pass
else:
token = token.strip()
stack[-1] += addnodes.desc_parameter(token, token)
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname
def describe_signature(self, signode, cls):
self.attach_modifiers(signode, cls)
signode += addnodes.desc_annotation('class ', 'class ')
self.attach_name(signode, cls.name)
def handle_signature(self, sig, signode):
"""Transform a PSschema signature into RST nodes."""
# first try the function pointer signature regex, it's more specific
name = sig
signode += addnodes.desc_name('', '')
objectname = self.env.temp_data.get('psdom:object')
ot = self.objtype
ws = wsplit_re.split(sig)
if ot == 'db':
sig_prefix = "database "
else:
sig_prefix = ot + " "
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
# for part in filter(None, ws):
# tnode = nodes.Text(part, part)
# pnode = addnodes.pending_xref(
# '', refdomain='psdom', reftype='type', reftarget=part,
# modname=None, classname=None)
# pnode = tnode
# signode += pnode
if len(ws) > 2:
dbname, tablename, columnname = ws
name = columnname
fullname = tablename + "." + columnname
elif len(ws) == 2:
if ot == 'table':
dbname, tablename = ws
dbname += "."
name = tablename
signode['table'] = tablename
signode += addnodes.desc_addname(dbname, dbname)
signode += addnodes.desc_name(tablename, tablename)
# fullname = dbname + "." + tablename
fullname = tablename
if ot == 'column':
tablename, columnname = ws
tablename += " "
signode += addnodes.desc_addname(tablename, tablename)
signode += addnodes.desc_name(columnname, columnname)
signode['table'] = tablename
fullname = tablename + "." + columnname
else:
if ot == 'table':
tablename = ws[0]
signode['table'] = tablename
dbname = self.options.get(
'db', self.env.temp_data.get('psdom:db'))
dbname += "."
self.env.temp_data['psdom:table'] = tablename
signode += addnodes.desc_addname(dbname, dbname)
signode += addnodes.desc_name(tablename, tablename)
signode['table'] = tablename
if ot == 'column':
columnname = ws[0]
signode['column'] = columnname
tablename = self.options.get(
'table', self.env.temp_data.get('psdom:table'))
tablename += "."
signode += addnodes.desc_addname(tablename, tablename)
signode += addnodes.desc_name(columnname, columnname)
if ot == 'db':
dbname = ws[0]
signode['db'] = dbname
name = dbname
self.env.temp_data['psdom:db'] = dbname
signode += addnodes.desc_name(dbname, dbname)
fullname = ws[0]
signode['fullname'] = fullname
return fullname
def handle_signature(self, sig, signode):
"""
Transform a PHP signature into RST nodes.
Returns (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
m = php_sig_re.match(sig)
if m is None:
raise ValueError
name_prefix, name, arglist, retann = m.groups()
if not name_prefix:
name_prefix = ""
# determine module and class name (if applicable), as well as full name
modname = self.options.get(
'namespace', self.env.temp_data.get('php:namespace'))
classname = self.env.temp_data.get('php:class')
separator = separators[self.objtype]
if self.objtype == 'global' or self.objtype == 'function':
add_module = False
modname = None
classname = None
fullname = name
else:
add_module = True
# name_prefix and a non-static method, means the classname was
# repeated. Trim off the <class>::
if name_prefix and self.objtype != 'staticmethod':
if name_prefix.startswith(classname):
name_prefix = name_prefix[len(classname):].rstrip('::')
classname = classname.rstrip('::')
fullname = name_prefix + classname + separator + name
elif name_prefix:
classname = classname.rstrip('::')
fullname = name_prefix + name
# Currently in a class, but not creating another class,
elif classname and not self.objtype in ['class', 'exception', 'interface']:
if not self.env.temp_data['php:in_class']:
name_prefix = classname + separator
fullname = classname + separator + name
else:
classname = ''
fullname = name
signode['namespace'] = modname
signode['class'] = self.class_name = classname
signode['fullname'] = fullname
sig_prefix = self.get_signature_prefix(sig)
if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if name_prefix:
if modname and not self.env.temp_data['php:in_class']:
name_prefix = modname + NS + name_prefix
signode += addnodes.desc_addname(name_prefix, name_prefix)
elif add_module and self.env.config.add_module_names:
if self.objtype == 'global':
nodetext = ''
signode += addnodes.desc_addname(nodetext, nodetext)
else:
modname = self.options.get(
'namespace', self.env.temp_data.get('php:namespace'))
if modname and not self.env.temp_data.get('php:in_class', False):
nodetext = modname + NS
signode += addnodes.desc_addname(nodetext, nodetext)
signode += addnodes.desc_name(name, name)
if not arglist:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname, name_prefix
signode += addnodes.desc_parameterlist()
stack = [signode[-1]]
for token in php_paramlist_re.split(arglist):
if token == '[':
opt = addnodes.desc_optional()
stack[-1] += opt
stack.append(opt)
elif token == ']':
try:
stack.pop()
except IndexError:
raise ValueError
elif not token or token == ',' or token.isspace():
pass
else:
token = token.strip()
stack[-1] += addnodes.desc_parameter(token, token)
if len(stack) != 1:
raise ValueError
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname, name_prefix
def handle_signature(self, sig, signode):
container_class_name = self.env.temp_data.get('swift:class')
container_class_type = self.env.temp_data.get('swift:class_type')
# split into method name and rest
first_anglebracket = sig.find('<')
first_paren = sig.find('(')
if first_anglebracket >= 0 and first_paren > first_anglebracket:
split_point = sig.find('>') + 1
else:
split_point = first_paren
# calculate generics
if first_anglebracket >= 0:
sp = sig[first_anglebracket:]
np = sp.find('>')
generics = sp[:np + 1]
else:
generics = None
method_name = sig[0:split_point]
# find method specialization
angle_bracket = method_name.find('<')
if angle_bracket >= 0:
method_name = method_name[:angle_bracket]
rest = sig[split_point:]
# split parameter list
parameter_list = None
depth = 0
for i, c in enumerate(rest):
if c == '(':
depth += 1
elif c == ')':
depth -= 1
if depth == 0:
parameter_list = rest[1:i]
rest = rest[i + 1:]
break
if parameter_list is not None and len(parameter_list) > 0:
parameters = self._parse_parameter_list(parameter_list)
else:
parameters = []
# check if it throws
throws = rest.find('throws') >= 0
# check for return type
return_type = None
arrow = rest.find('->')
if arrow >= 0:
return_type = rest[arrow + 2:].strip()
# build signature and add nodes
signature = ''
if self.objtype == 'static_method':
signode += addnodes.desc_addname("static", "static func ")
elif self.objtype == 'class_method':
signode += addnodes.desc_addname("class", "class func ")
elif self.objtype != 'init':
signode += addnodes.desc_addname("func", "func ")
if self.objtype == 'init':
signode += addnodes.desc_name('init', 'init')
signature += 'init('
for p in parameters:
if p['name'] == p['variable_name']:
signature += p['name'] + ':'
else:
signature += p['name'] + ' ' + p['variable_name'] + ':'
signature += ')'
else:
signode += addnodes.desc_name(method_name, method_name)
signature += method_name
signature += '('
for p in parameters:
if p['name'] == p['variable_name']:
signature += p['name'] + ':'
else:
signature += p['name'] + ' ' + p['variable_name'] + ':'
signature += ')'
if generics:
signode += addnodes.desc_addname(generics, generics)
params = []
sig = ''
for p in parameters:
if p['name'] == p['variable_name']:
param = p['name'] + ': ' # + p['type']
sig += p['name'] + ':'
else:
param = p['name'] + ' ' + p[
'variable_name'] + ':' # + p['type']
sig += p['name'] + ' ' + p['variable_name'] + ':'
#if p['default']:
# param += ' = ' + p['default']
paramNode = addnodes.desc_parameter(param, param)
paramXref = addnodes.pending_xref('',
refdomain='swift',
reftype='type',
reftarget=p['type'])
paramXref += nodes.Text(p['type'], p['type'])
paramNode += paramXref
if p['default']:
paramNode += nodes.Text(' = ' + p['default'],
' = ' + p['default'])
params.append(paramNode)
signode += addnodes.desc_parameterlist(sig, "", *params)
title = signature
if throws:
signode += addnodes.desc_annotation("throws", "throws")
# signature += "throws"
if return_type:
paramNode = addnodes.desc_returns('', '')
paramXref = addnodes.pending_xref('',
refdomain='swift',
reftype='type',
reftarget=return_type)
paramXref += nodes.Text(return_type, return_type)
paramNode += paramXref
signode += paramNode
# signode += addnodes.desc_returns(return_type, return_type)
#signature += "-" + return_type
#if container_class_type == 'protocol':
# signature += "-protocol"
#if self.objtype == 'static_method':
# signature += '-static'
#elif self.objtype == 'class_method':
# signature += '-class'
if container_class_name:
return (container_class_name + '.' +
title), (container_class_name + '.' + signature), True
return title, signature, True
def handle_signature(self, sig, signode):
methods, path = sig
signode += addnodes.desc_annotation('endpoint ', 'endpoint ')
signode += addnodes.desc_addname(methods + ' ', methods + ' ')
signode += addnodes.desc_name(path, path)
def handle_signature(self, sig, signode):
if debug.flags.disable_docs_edgeql_validation:
signode['eql-fullname'] = fullname = re.split(r'\(| ', sig)[0]
signode['eql-signature'] = sig
mod, name = fullname.split('::')
signode['eql-module'] = mod
signode['eql-name'] = name
return fullname
from edb.edgeql.parser import parser as edgeql_parser
from edb.edgeql import ast as ql_ast
from edb.edgeql import codegen as ql_gen
parser = edgeql_parser.EdgeQLBlockParser()
try:
astnode = parser.parse(f'CREATE ABSTRACT CONSTRAINT {sig};')[0]
except Exception as ex:
raise shared.DirectiveParseError(
self,
f'could not parse constraint signature {sig!r}',
cause=ex)
if (not isinstance(astnode, ql_ast.CreateConstraint)
or not isinstance(astnode.name, ql_ast.ObjectRef)):
raise shared.DirectiveParseError(
self, f'EdgeQL parser returned unsupported AST')
modname = astnode.name.module
constr_name = astnode.name.name
if not modname:
raise shared.DirectiveParseError(
self, f'Missing module in EdgeQL constraint declaration')
constr_repr = ql_gen.EdgeQLSourceGenerator.to_source(astnode)
m = re.match(
r'''(?xs)
^
CREATE\sABSTRACT\sCONSTRAINT\s
(?P<f>.*?)(?:\s*ON(?P<subj>.*))?
$
''', constr_repr)
if not m or not m.group('f'):
raise shared.DirectiveParseError(
self, f'could not recreate constraint signature from AST')
constr_repr = m.group('f')
signode['eql-module'] = modname
signode['eql-name'] = constr_name
signode['eql-fullname'] = fullname = f'{modname}::{constr_name}'
signode['eql-signature'] = constr_repr
subject = m.group('subj')
if subject:
subject = subject.strip()[1:-1]
signode['eql-subjexpr'] = subject
signode['eql-signature'] += f' ON ({subject})'
signode += s_nodes.desc_annotation('constraint', 'constraint')
signode += d_nodes.Text(' ')
signode += s_nodes.desc_name(fullname, fullname)
return fullname
def handle_signature(self, sig, signode):
parser = edgeql_parser.EdgeQLBlockParser()
try:
astnode = parser.parse(
f'CREATE FUNCTION {sig} FROM SQL FUNCTION "xxx";')[0]
except Exception as ex:
raise shared.DirectiveParseError(
self, f'could not parse function signature {sig!r}', cause=ex)
if (not isinstance(astnode, ql_ast.CreateFunction)
or not isinstance(astnode.name, ql_ast.ObjectRef)):
raise shared.DirectiveParseError(
self, f'EdgeQL parser returned unsupported AST')
modname = astnode.name.module
funcname = astnode.name.name
if not modname:
raise shared.DirectiveParseError(
self, f'EdgeQL function declaration is missing namespace')
func_repr = ql_gen.EdgeQLSourceGenerator.to_source(astnode)
m = re.match(
r'''(?xs)
^
CREATE\sFUNCTION\s
(?P<f>.*?)
\sFROM\sSQL\sFUNCTION
.*$
''', func_repr)
if not m or not m.group('f'):
raise shared.DirectiveParseError(
self, f'could not recreate function signature from AST')
func_repr = m.group('f')
signode['eql-module'] = modname
signode['eql-name'] = funcname
signode['eql-fullname'] = fullname = f'{modname}::{funcname}'
signode['eql-signature'] = func_repr
signode += s_nodes.desc_annotation('function', 'function')
signode += d_nodes.Text(' ')
signode += s_nodes.desc_name(fullname, fullname)
params = s_nodes.desc_parameterlist()
for idx, param in enumerate(astnode.args):
name = param.name
if not name:
name = f'${idx}'
param_repr = ql_gen.EdgeQLSourceGenerator.to_source(param)
param_node = s_nodes.desc_parameter(param_repr, param_repr)
param_node['eql-name'] = name
params += param_node
signode += params
ret_repr = ql_gen.EdgeQLSourceGenerator.to_source(astnode.returning)
if astnode.set_returning is ql_ast.SetQualifier.SET_OF:
ret_repr = f'SET OF {ret_repr}'
signode += s_nodes.desc_returns(ret_repr, ret_repr)
return fullname
def handle_signature(self, sig: str,
signode: desc_signature) -> Tuple[str, str]:
"""Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
m = py_sig_re.match(sig)
if m is None:
raise ValueError
prefix, name, arglist, retann = m.groups()
# determine module and class name (if applicable), as well as full name
modname = self.options.get('module',
self.env.ref_context.get('py:module'))
classname = self.env.ref_context.get('py:class')
if classname:
add_module = False
if prefix and (prefix == classname
or prefix.startswith(classname + ".")):
fullname = prefix + name
# class name is given again in the signature
prefix = prefix[len(classname):].lstrip('.')
elif prefix:
# class name is given in the signature, but different
# (shouldn't happen)
fullname = classname + '.' + prefix + name
else:
# class name is not given in the signature
fullname = classname + '.' + name
else:
add_module = True
if prefix:
classname = prefix.rstrip('.')
fullname = prefix + name
else:
classname = ''
fullname = name
signode['module'] = modname
signode['class'] = classname
signode['fullname'] = fullname
sig_prefix = self.get_signature_prefix(sig)
if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if prefix:
signode += addnodes.desc_addname(prefix, prefix)
elif add_module and self.env.config.add_module_names:
if modname and modname != 'exceptions':
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
nodetext = modname + '.'
signode += addnodes.desc_addname(nodetext, nodetext)
signode += addnodes.desc_name(name, name)
if arglist:
try:
signode += _parse_arglist(arglist)
except SyntaxError:
# fallback to parse arglist original parser.
# it supports to represent optional arguments (ex. "func(foo [, bar])")
_pseudo_parse_arglist(signode, arglist)
except NotImplementedError as exc:
logger.warning("could not parse arglist (%r): %s", arglist,
exc)
_pseudo_parse_arglist(signode, arglist)
else:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
anno = self.options.get('annotation')
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, prefix
def parse_signature(self, sig, signode):
"""
Transform a Python signature into RST nodes.
Returns (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
m = py_sig_re.match(sig)
if m is None:
raise ValueError
classname, name, arglist, retann = m.groups()
if self.env.currclass:
add_module = False
if classname and classname.startswith(self.env.currclass):
fullname = classname + name
# class name is given again in the signature
classname = classname[len(self.env.currclass):].lstrip('.')
elif classname:
# class name is given in the signature, but different
# (shouldn't happen)
fullname = self.env.currclass + '.' + classname + name
else:
# class name is not given in the signature
fullname = self.env.currclass + '.' + name
else:
add_module = True
fullname = classname and classname + name or name
prefix = self.get_signature_prefix(sig)
if prefix:
signode += addnodes.desc_annotation(prefix, prefix)
if classname:
signode += addnodes.desc_addname(classname, classname)
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
elif add_module and self.env.config.add_module_names:
modname = self.options.get('module', self.env.currmodule)
if modname and modname != 'exceptions':
nodetext = modname + '.'
signode += addnodes.desc_addname(nodetext, nodetext)
signode += addnodes.desc_name(name, name)
if not arglist:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname, classname
signode += addnodes.desc_parameterlist()
stack = [signode[-1]]
for token in py_paramlist_re.split(arglist):
if token == '[':
opt = addnodes.desc_optional()
stack[-1] += opt
stack.append(opt)
elif token == ']':
try:
stack.pop()
except IndexError:
raise ValueError
elif not token or token == ',' or token.isspace():
pass
else:
token = token.strip()
stack[-1] += addnodes.desc_parameter(token, token)
if len(stack) != 1:
raise ValueError
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname, classname
def handle_signature(self, sig, signode):
ret = super(PyAbstractMethod, self).handle_signature(sig, signode)
signode.insert(0, addnodes.desc_annotation('abstractmethod ',
'abstractmethod '))
return ret
def handle_signature(self, sig, signode):
ret = super(PyAwaitableMixin, self).handle_signature(sig, signode)
signode.insert(0, addnodes.desc_annotation('awaitable ', 'awaitable '))
return ret
def handle_signature(self, sig, signode):
ret = super().handle_signature(sig, signode)
signode.insert(
0, addnodes.desc_annotation("abstractmethod ", "abstractmethod "))
return ret
def handle_signature(self, sig, signode):
signode += addnodes.desc_annotation(text="property ")
signode += addnodes.desc_name(text=sig)
return sig
def handle_signature(self, sig: str,
signode: desc_signature) -> Tuple[str, str]:
"""Breaks down construct signatures
Parses out prefix and argument list from construct definition. The
namespace and class will be determined by the nesting of domain
directives.
"""
sig = sig.strip()
if '(' in sig and sig[-1:] == ')':
member, arglist = sig.split('(', 1)
member = member.strip()
arglist = arglist[:-1].strip()
else:
member = sig
arglist = None
# If construct is nested, prefix the current prefix
prefix = self.env.ref_context.get('js:object', None)
mod_name = self.env.ref_context.get('js:module')
name = member
try:
member_prefix, member_name = member.rsplit('.', 1)
except ValueError:
member_name = name
member_prefix = ''
finally:
name = member_name
if prefix and member_prefix:
prefix = '.'.join([prefix, member_prefix])
elif prefix is None and member_prefix:
prefix = member_prefix
fullname = name
if prefix:
fullname = '.'.join([prefix, name])
signode['module'] = mod_name
signode['object'] = prefix
signode['fullname'] = fullname
display_prefix = self.get_display_prefix()
if display_prefix:
signode += addnodes.desc_annotation('', '', *display_prefix)
actual_prefix = None
if prefix:
actual_prefix = prefix
elif mod_name:
actual_prefix = mod_name
if actual_prefix:
addName = addnodes.desc_addname('', '')
for p in actual_prefix.split('.'):
addName += addnodes.desc_sig_name(p, p)
addName += addnodes.desc_sig_punctuation('.', '.')
signode += addName
signode += addnodes.desc_name('', '',
addnodes.desc_sig_name(name, name))
if self.has_arguments:
if not arglist:
signode += addnodes.desc_parameterlist()
else:
_pseudo_parse_arglist(signode, arglist)
return fullname, prefix
def handle_signature(self, sig, signode):
parser = edgeql_parser.EdgeQLBlockParser()
try:
astnode = parser.parse(f'CREATE ABSTRACT CONSTRAINT {sig};')[0]
except Exception as ex:
raise shared.DirectiveParseError(
self,
f'could not parse constraint signature {sig!r}',
cause=ex)
if (not isinstance(astnode, ql_ast.CreateConstraint)
or not isinstance(astnode.name, ql_ast.ObjectRef)):
raise shared.DirectiveParseError(
self, f'EdgeQL parser returned unsupported AST')
modname = astnode.name.module
constr_name = astnode.name.name
if not modname:
raise shared.DirectiveParseError(
self, f'Missing module in EdgeQL constraint declaration')
constr_repr = ql_gen.EdgeQLSourceGenerator.to_source(astnode)
m = re.match(
r'''(?xs)
^
CREATE\sABSTRACT\sCONSTRAINT\s
(?P<f>.*?)(?:\s*ON(?P<subj>.*))?
$
''', constr_repr)
if not m or not m.group('f'):
raise shared.DirectiveParseError(
self, f'could not recreate constraint signature from AST')
constr_repr = m.group('f')
signode['eql-module'] = modname
signode['eql-name'] = constr_name
signode['eql-fullname'] = fullname = f'{modname}::{constr_name}'
signode['eql-signature'] = constr_repr
subject = m.group('subj')
if subject:
subject = subject.strip()[1:-1]
signode['eql-subjexpr'] = subject
signode['eql-signature'] += f' ON ({subject})'
signode += s_nodes.desc_annotation('constraint', 'constraint')
signode += d_nodes.Text(' ')
signode += s_nodes.desc_name(fullname, fullname)
params = s_nodes.desc_parameterlist()
for idx, param in enumerate(astnode.args):
name = param.name
if not name:
name = f'${idx}'
param_repr = ql_gen.EdgeQLSourceGenerator.to_source(param)
param_node = s_nodes.desc_parameter(param_repr, param_repr)
param_node['eql-name'] = name
params += param_node
signode += params
return fullname
def handle_signature(self, sig, signode):
# type: (unicode, addnodes.desc_signature) -> Tuple[unicode, unicode]
"""Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
m = py_sig_re.match(sig) # type: ignore
if m is None:
raise ValueError
name_prefix, name, arglist, retann = m.groups()
# determine module and class name (if applicable), as well as full name
modname = self.options.get('module',
self.env.ref_context.get('py:module'))
classname = self.env.ref_context.get('py:class')
if classname:
add_module = False
if name_prefix and name_prefix.startswith(classname):
fullname = name_prefix + name
# class name is given again in the signature
name_prefix = name_prefix[len(classname):].lstrip('.')
elif name_prefix:
# class name is given in the signature, but different
# (shouldn't happen)
fullname = classname + '.' + name_prefix + name
else:
# class name is not given in the signature
fullname = classname + '.' + name
else:
add_module = True
if name_prefix:
classname = name_prefix.rstrip('.')
fullname = name_prefix + name
else:
classname = ''
fullname = name
signode['module'] = modname
signode['class'] = classname
signode['fullname'] = fullname
sig_prefix = self.get_signature_prefix(sig)
if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if name_prefix:
signode += addnodes.desc_addname(name_prefix, name_prefix)
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
elif add_module and self.env.config.add_module_names:
modname = self.options.get('module',
self.env.ref_context.get('py:module'))
if modname and modname != 'exceptions':
nodetext = modname + '.'
signode += addnodes.desc_addname(nodetext, nodetext)
anno = self.options.get('annotation')
signode += addnodes.desc_name(name, name)
if not arglist:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, name_prefix
_pseudo_parse_arglist(signode, arglist)
if retann:
signode += addnodes.desc_returns(retann, retann)
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return fullname, name_prefix
def handle_signature(self, sig, signode):
signode += addnodes.desc_annotation('REST type ', 'REST type ')
signode += addnodes.desc_name(sig, sig)
def handle_signature(self, sig, signode):
self.env.temp_data['current-class'] = sig
signode += addnodes.desc_annotation('class', ' class ')
signode += addnodes.desc_name(sig, sig)
return sig
def handle_signature(self, sig, signode):
if debug.flags.disable_docs_edgeql_validation:
signode['eql-fullname'] = fullname = sig.split('(')[0]
signode['eql-signature'] = sig
mod, name = fullname.split('::')
signode['eql-module'] = mod
signode['eql-name'] = name
return fullname
from edb.edgeql.parser import parser as edgeql_parser
from edb.edgeql import ast as ql_ast
from edb.edgeql import codegen as ql_gen
from edb.edgeql import qltypes
parser = edgeql_parser.EdgeQLBlockParser()
try:
astnode = parser.parse(
f'CREATE FUNCTION {sig} USING SQL FUNCTION "xxx";')[0]
except Exception as ex:
raise shared.DirectiveParseError(
self, f'could not parse function signature {sig!r}', cause=ex)
if (not isinstance(astnode, ql_ast.CreateFunction)
or not isinstance(astnode.name, ql_ast.ObjectRef)):
raise shared.DirectiveParseError(
self, f'EdgeQL parser returned unsupported AST')
modname = astnode.name.module
funcname = astnode.name.name
if not modname:
raise shared.DirectiveParseError(
self, f'EdgeQL function declaration is missing namespace')
func_repr = ql_gen.EdgeQLSourceGenerator.to_source(astnode)
m = re.match(
r'''(?xs)
^
CREATE\sFUNCTION\s
(?P<f>.*?)
\sUSING\sSQL\sFUNCTION
.*$
''', func_repr)
if not m or not m.group('f'):
raise shared.DirectiveParseError(
self, f'could not recreate function signature from AST')
func_repr = m.group('f')
signode['eql-module'] = modname
signode['eql-name'] = funcname
signode['eql-fullname'] = fullname = f'{modname}::{funcname}'
signode['eql-signature'] = func_repr
signode += s_nodes.desc_annotation('function', 'function')
signode += d_nodes.Text(' ')
signode += s_nodes.desc_name(fullname, fullname)
ret_repr = ql_gen.EdgeQLSourceGenerator.to_source(astnode.returning)
if astnode.returning_typemod is qltypes.TypeModifier.SetOfType:
ret_repr = f'SET OF {ret_repr}'
elif astnode.returning_typemod is qltypes.TypeModifier.OptionalType:
ret_repr = f'OPTIONAL {ret_repr}'
signode += s_nodes.desc_returns(ret_repr, ret_repr)
return fullname
def handle_signature(self, sig, signode):
prefix = 'enum' + ' '
signode += addnodes.desc_annotation(prefix, prefix)
signode += addnodes.desc_name(sig, sig)
return self.get_fullname(sig)
def handle_signature(self, sig, signode):
signode += addnodes.desc_name(sig, sig)
signode += addnodes.desc_annotation(" (Customize Option)",
" (Customize Option)")
return sig
def handle_exception_sig(self, sig, signode):
fullname = self._resolve_module_name(signode, "", sig)
signode += addnodes.desc_annotation(": exception", ": exception")
return fullname
def _handle_signature(self, cid, lineno, sig, signode):
# type: (str, addnodes.desc_signature) -> Tuple[str, str]
"""Transform a Python signature into RST nodes.
Return (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
This is the xml string result of signode, whitespace is not
equivalent for readability.
<desc_signature
class=""
first="False"
fullname="com.google.fonts/check/all_glyphs_have_codepoints"
module="fontbakery.profiles.cmap"
>
<desc_annotation
xml:space="preserve">FontBakeryCheck </desc_annotation>
<desc_addname
xml:space="preserve">fontbakery.profiles.cmap.</desc_addname>
<desc_name
xml:space="preserve">com_google_fonts_check_all_glyphs_have_codepoints</desc_name>
<desc_parameterlist
xml:space="preserve">
<desc_parameter xml:space="preserve">ttFont</desc_parameter>
</desc_parameterlist>
</desc_signature>
"""
m = py_sig_re.match(sig)
if m is None:
# this is the immediate fail!!!
raise ValueError
prefix, name, arglist, retann = m.groups()
# print('prefix, name, arglist, retann =', prefix, name, arglist, retann)
# > prefix, name, arglist, retann = None com_google_fonts_check_all_glyphs_have_codepoints ttFont None
# determine module and class name (if applicable), as well as full name
modname = self.options.get('module',
self.env.ref_context.get('py:module'))
classname = self.env.ref_context.get('py:class')
if classname:
add_module = False
if prefix and (prefix == classname
or prefix.startswith(classname + ".")):
fullname = prefix + name
# class name is given again in the signature
prefix = prefix[len(classname):].lstrip('.')
elif prefix:
# class name is given in the signature, but different
# (shouldn't happen)
fullname = classname + '.' + prefix + name
else:
# class name is not given in the signature
fullname = classname + '.' + name
else:
add_module = True
if prefix:
classname = prefix.rstrip('.')
fullname = prefix + name
else:
classname = ''
fullname = name
signode['module'] = modname
signode['class'] = classname
signode['fullname'] = fullname
signode.attributes['lineno'] = lineno
#sig_prefix = self.get_signature_prefix(sig)
#if sig_prefix:
# signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if prefix:
signode += addnodes.desc_addname(prefix, prefix)
elif add_module and self.env.config.add_module_names:
if modname and modname != 'exceptions':
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
#nodetext = modname + ' ID: '
#signode += addnodes.desc_addname(nodetext, nodetext)
pass
signode += addnodes.desc_name(name, cid)
if arglist:
_pseudo_parse_arglist(signode, arglist)
else:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
anno = self.options.get('annotation')
if anno:
signode += addnodes.desc_annotation(' ' + anno, ' ' + anno)
return cid, prefix
def handle_signature(self, sig, signode):
ret = super().handle_signature(sig, signode)
signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
return ret
def envy_resolve(app, doctree, fromdocname):
objects = app.env.domaindata['envy']['objects']
# add uplink info
for holder in doctree.traverse(uplink_placeholder):
obj = objects[holder.name]
links = []
for sp, pos, name, variants in obj.uplinks:
signode = addnodes.desc_signature('', '')
signode['first'] = False
signode += make_refnode(app.builder, fromdocname, sp.docname,
sp.iname + '-' + sp.name,
addnodes.desc_addname(sp.name,
sp.name), sp.name)
text = ' {}: {}'.format(pos, name)
signode += addnodes.desc_name(text, text)
if variants is not None:
text = ' [{}]'.format(variants)
signode += addnodes.desc_annotation(text, text)
links.append(signode)
holder.replace_self(links)
# add subnode list
for holder in doctree.traverse(sub_placeholder):
obj = objects[holder.name]
add_variant = False
for pos, name, child, variants in obj.subs:
if variants is not None:
add_variant = True
table = nodes.table()
headers = [(1, 'Address'), (1, 'Name'), (10, 'Description')]
if add_variant:
headers.insert(1, (1, 'Variants'))
tgroup = nodes.tgroup(cols=len(headers))
table += tgroup
for colwidth, header in headers:
tgroup += nodes.colspec(colwidth=colwidth)
thead = nodes.thead()
tgroup += thead
headrow = nodes.row()
for colwidth, header in headers:
entry = nodes.entry()
para = nodes.paragraph()
entry += para
para += nodes.Text(header, header)
headrow += entry
thead += headrow
tbody = nodes.tbody()
tgroup += tbody
for pos, name, child, variants in obj.subs:
row = nodes.row()
row += wrap_text_entry(pos)
if add_variant:
row += wrap_text_entry('all' if variants is None else variants)
row += wrap_text_entry(name)
entry = nodes.entry()
para = nodes.paragraph()
entry += para
para += make_refnode(app.builder, fromdocname, child.docname,
child.iname + '-' + child.name,
nodes.Text(child.brief,
child.brief), child.brief)
row += entry
tbody += row
holder.replace_self([table])
def process_motor_nodes(app, doctree):
# Search doctree for Motor's methods and attributes whose docstrings were
# copied from PyMongo, and fix them up for Motor:
# 1. Add a 'callback' param (sometimes optional, sometimes required) to
# all Motor Tornado methods. If the PyMongo method took no params, we
# create a parameter-list from scratch, otherwise we edit PyMongo's
# list.
# 2. Remove all version annotations like "New in version 2.0" since
# PyMongo's version numbers are meaningless in Motor's docs.
# 3. Remove "seealso" directives that reference PyMongo's docs.
#
# We do this here, rather than by registering a callback to Sphinx's
# 'autodoc-process-signature' event, because it's way easier to handle the
# parsed doctree before it's turned into HTML than it is to update the RST.
for objnode in doctree.traverse(desc):
if objnode['objtype'] in ('method', 'attribute'):
signature_node = find_by_path(objnode, [desc_signature])[0]
name = '.'.join(
[signature_node['module'], signature_node['fullname']])
assert name.startswith('motor.')
obj_motor_info = motor_info.get(name)
if obj_motor_info:
desc_content_node = find_by_path(objnode, [desc_content])[0]
if obj_motor_info['is_pymongo_docstring']:
maybe_warn_about_code_block(name, desc_content_node)
if obj_motor_info['is_async_method']:
# Might be a handwritten RST with "coroutine" already.
if not has_coro_annotation(signature_node):
coro_annotation = addnodes.desc_annotation(
'coroutine ',
'coroutine ',
classes=['coro-annotation'])
signature_node.insert(0, coro_annotation)
if not is_asyncio_api(name):
retval = ("If a callback is passed, returns None, else"
" returns a Future.")
callback_p = paragraph('', Text(retval))
# Find the parameter list.
parameters_nodes = find_by_path(
desc_content_node, [
field_list, field, field_body,
(bullet_list, paragraph)
])
if parameters_nodes:
parameters_node = parameters_nodes[0]
else:
# PyMongo method has no parameters, create an empty
# params list
parameters_node = bullet_list()
parameters_field_list_node = field_list(
'',
field('', field_name('', 'Parameters '),
field_body('', parameters_node)))
desc_content_node.append(
parameters_field_list_node)
insert_callback(parameters_node)
if retval not in str(desc_content_node):
desc_content_node.append(callback_p)
if obj_motor_info['is_pymongo_docstring']:
# Remove all "versionadded", "versionchanged" and
# "deprecated" directives from the docs we imported from
# PyMongo
version_nodes = find_by_path(desc_content_node,
[versionmodified])
for version_node in version_nodes:
version_node.parent.remove(version_node)
# Remove all "seealso" directives that contain :doc:
# references from PyMongo's docs
seealso_nodes = find_by_path(desc_content_node, [seealso])
for seealso_node in seealso_nodes:
if 'reftype="doc"' in str(seealso_node):
seealso_node.parent.remove(seealso_node)
def _add_signature_prefix(self, signode):
if self.objtype != 'function':
sig_prefix = self.objtype + ' '
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
def handle_signature(self, sig, signode):
"""
Transform a Fortran signature into RST nodes.
Returns (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
m = f_sig_re.match(sig)
if m is None:
raise ValueError
ftype, objtype, modname, typename, name, arglist = m.groups()
if not typename: typename = ""
# determine module, type, shape and attributes
modname = (modname and modname[:-1]) or self.options.get(
'module', self.env.temp_data.get('f:module'))
if typename:
name = typename[:-1]
attrs = self.options.get('attrs')
shape = parse_shape(self.options.get('shape'))
ftype = ftype or self.options.get('type')
if self.objtype=='typefield' and not typename:
raise ValueError
#if typename: name = typename+'%'+name
#fullname = name
#if modname:
if self.objtype=='program':
fullname = name
else:
fullname = (modname or '_') + f_sep + name
signode['module'] = modname
signode['type'] = typename
signode['fullname'] = fullname
# Add "function" or "subroutine" tag
sig_prefix = self.get_signature_prefix(sig)
if objtype or sig_prefix:
objtype = objtype or sig_prefix
signode += addnodes.desc_annotation(objtype+' ', objtype+' ')
# Add module
if self.env.config.add_module_names and modname and self.objtype!='typefield':
nodetext = modname + f_sep
signode += addnodes.desc_addname(nodetext, nodetext)
# Add name
signode += addnodes.desc_name(name, name)
# In the parenthesis
if self.needs_arglist(): # call for functions and subroutines
if arglist: # Calling arguments
_pseudo_parse_arglist(signode, arglist)
elif self.needs_arglist(): # for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
elif arglist and not shape: # Declare shape instead of arguments (variables)
shape = arglist
# Add remaining
self.add_shape_and_attrs(signode, modname, ftype, shape, attrs)
return fullname, ftype
def handle_signature(self, sig, signode):
ret = super(PySyncSignal, self).handle_signature(sig, signode)
signode.insert(
0,
addnodes.desc_annotation('coroutine signal ', 'coroutine signal '))
return ret
def handle_signature(self, sig, signode):
"""
Transform a Ruby signature into RST nodes.
Returns (fully qualified name of the thing, classname if any).
If inside a class, the current class name is handled intelligently:
* it is stripped from the displayed name if present
* it is added to the full name (return value) if not present
"""
m = rb_sig_re.match(sig)
if m is None:
raise ValueError
name_prefix, name, arglist, retann = m.groups()
if not name_prefix:
name_prefix = ""
# determine module and class name (if applicable), as well as full name
modname = self.options.get('module',
self.env.temp_data.get('rb:module'))
classname = self.env.temp_data.get('rb:class')
if self.objtype == 'global':
add_module = False
modname = None
classname = None
fullname = name
elif classname:
add_module = False
if name_prefix and name_prefix.startswith(classname):
fullname = name_prefix + name
# class name is given again in the signature
name_prefix = name_prefix[len(classname):].lstrip('.')
else:
separator = separators[self.objtype]
fullname = classname + separator + name_prefix + name
else:
add_module = True
if name_prefix:
classname = name_prefix.rstrip('.')
fullname = name_prefix + name
else:
classname = ''
fullname = name
signode['module'] = modname
signode['class'] = self.class_name = classname
signode['fullname'] = fullname
sig_prefix = self.get_signature_prefix(sig)
if sig_prefix:
signode += addnodes.desc_annotation(sig_prefix, sig_prefix)
if name_prefix:
signode += addnodes.desc_addname(name_prefix, name_prefix)
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
elif add_module and self.env.config.add_module_names:
if self.objtype == 'global':
nodetext = ''
signode += addnodes.desc_addname(nodetext, nodetext)
else:
modname = self.options.get('module',
self.env.temp_data.get('rb:module'))
if modname and modname != 'exceptions':
nodetext = modname + separators[self.objtype]
signode += addnodes.desc_addname(nodetext, nodetext)
signode += addnodes.desc_name(name, name)
if not arglist:
if self.needs_arglist():
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname, name_prefix
signode += addnodes.desc_parameterlist()
stack = [signode[-1]]
for token in rb_paramlist_re.split(arglist):
if token == '[':
opt = addnodes.desc_optional()
stack[-1] += opt
stack.append(opt)
elif token == ']':
try:
stack.pop()
except IndexError:
raise ValueError
elif not token or token == ',' or token.isspace():
pass
else:
token = token.strip()
stack[-1] += addnodes.desc_parameter(token, token)
if len(stack) != 1:
raise ValueError
if retann:
signode += addnodes.desc_returns(retann, retann)
return fullname, name_prefix
