def parse_c_signature(signode, sig, desctype):
"""Transform a C (or C++) signature into RST nodes."""
# first try the function pointer signature regex, it's more specific
m = c_funcptr_sig_re.match(sig)
if m is None:
m = c_sig_re.match(sig)
if m is None:
raise ValueError('no match')
rettype, name, arglist, const = m.groups()
signode += addnodes.desc_type("", "")
parse_c_type(signode[-1], rettype)
try:
classname, funcname = name.split('::', 1)
classname += '::'
signode += addnodes.desc_classname(classname, classname)
signode += addnodes.desc_name(funcname, funcname)
# name (the full name) is still both parts
except ValueError:
signode += addnodes.desc_name(name, name)
# clean up parentheses from canonical name
m = c_funcptr_name_re.match(name)
if m:
name = m.group(1)
if not arglist:
if desctype == 'cfunction':
# for functions, add an empty parameter list
signode += addnodes.desc_parameterlist()
return name
paramlist = addnodes.desc_parameterlist()
arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
# this messes up function pointer types, but not too badly ;)
args = arglist.split(',')
for arg in args:
arg = arg.strip()
param = addnodes.desc_parameter('', '', noemph=True)
try:
ctype, argname = arg.rsplit(' ', 1)
except ValueError:
# no argument name given, only the type
parse_c_type(param, arg)
else:
parse_c_type(param, ctype)
param += nodes.emphasis(' ' + argname, ' ' + argname)
paramlist += param
signode += paramlist
if const:
signode += addnodes.desc_classname(const, const)
return name
def parse_c_signature(signode, sig, desctype):
"""Transform a C (or C++) signature into RST nodes."""
# first try the function pointer signature regex, it's more specific
m = c_funcptr_sig_re.match(sig)
if m is None:
m = c_sig_re.match(sig)
if m is None:
raise ValueError('no match')
rettype, name, arglist, const = m.groups()
signode += addnodes.desc_type("", "")
parse_c_type(signode[-1], rettype)
try:
classname, funcname = name.split('::', 1)
classname += '::'
signode += addnodes.desc_classname(classname, classname)
signode += addnodes.desc_name(funcname, funcname)
# name (the full name) is still both parts
except ValueError:
signode += addnodes.desc_name(name, name)
# clean up parentheses from canonical name
m = c_funcptr_name_re.match(name)
if m:
name = m.group(1)
if not arglist:
if desctype == 'cfunction':
# for functions, add an empty parameter list
signode += addnodes.desc_parameterlist()
return name
paramlist = addnodes.desc_parameterlist()
arglist = arglist.replace('`', '').replace('\\ ', '') # remove markup
# this messes up function pointer types, but not too badly ;)
args = arglist.split(',')
for arg in args:
arg = arg.strip()
param = addnodes.desc_parameter('', '', noemph=True)
try:
ctype, argname = arg.rsplit(' ', 1)
except ValueError:
# no argument name given, only the type
parse_c_type(param, arg)
else:
parse_c_type(param, ctype)
param += nodes.emphasis(' '+argname, ' '+argname)
paramlist += param
signode += paramlist
if const:
signode += addnodes.desc_classname(const, const)
return name
def parse_option_desc(signode, sig):
"""Transform an option description into RST nodes."""
count = 0
firstname = ''
for m in option_desc_re.finditer(sig):
prefix, optname, args = m.groups()
if count:
signode += addnodes.desc_classname(', ', ', ')
signode += addnodes.desc_name(prefix + optname, prefix + optname)
signode += addnodes.desc_classname(args, args)
if not count:
firstname = optname
count += 1
if not firstname:
raise ValueError
return firstname
def parse_option_desc(signode, sig):
"""Transform an option description into RST nodes."""
count = 0
firstname = ''
for m in option_desc_re.finditer(sig):
prefix, optname, args = m.groups()
if count:
signode += addnodes.desc_classname(', ', ', ')
signode += addnodes.desc_name(prefix+optname, prefix+optname)
signode += addnodes.desc_classname(args, args)
if not count:
firstname = optname
count += 1
if not firstname:
raise ValueError
return firstname
def decorate_signatures(desc, classname):
prefix = classname + "."
for child in desc.children:
if isinstance(child, desc_signature) and isinstance(
child[0], desc_name):
new_desc_classname = desc_classname("", prefix)
child.insert(0, new_desc_classname)
def parse_directive(env, sig, signode):
if not sig.startswith('.'):
dec_sig = '.. %s::' % sig
signode += addnodes.desc_name(dec_sig, dec_sig)
return sig
m = dir_sig_re.match(sig)
if not m:
signode += addnodes.desc_name(sig, sig)
return sig
name, args = m.groups()
dec_name = '.. %s::' % name
signode += addnodes.desc_name(dec_name, dec_name)
signode += addnodes.desc_classname(args, args)
return name
def parse_directive(env, sig, signode):
if not sig.startswith('.'):
dec_sig = '.. %s::' % sig
signode += addnodes.desc_name(dec_sig, dec_sig)
return sig
m = dir_sig_re.match(sig)
if not m:
signode += addnodes.desc_name(sig, sig)
return sig
name, args = m.groups()
dec_name = '.. %s::' % name
signode += addnodes.desc_name(dec_name, dec_name)
signode += addnodes.desc_classname(args, args)
return name
def run(self):
module_path, member_name = self.arguments[0].rsplit('.', 1)
member_data = getattr(import_module(module_path), member_name)
code = pformat(member_data, 2, width=68)
literal = nodes.literal_block(code, code)
literal['language'] = 'python'
title = (getattr(member_data, 'title', member_name)
or getattr(member_data, 'label', member_name) or "")
justification = getattr(member_data, 'justification', "")
muted = getattr(member_data, 'muted', False)
if hasattr(member_data, 'message_template'):
text = getattr(member_data, 'message_template')
else:
text = getattr(member_data, 'message')
result = [addnodes.desc_classname(text="Feedback Function: " + title)]
lst = nodes.bullet_list()
item = nodes.list_item()
lst += item
item += nodes.strong(text="Label: ")
item += nodes.inline(text=member_name)
if muted:
item = nodes.list_item()
lst += item
item += nodes.emphasis(text="Muted by default")
item = nodes.list_item()
lst += item
item += nodes.strong(text="Justification: ")
item += nodes.inline(text=justification)
item = nodes.list_item()
lst += item
item += nodes.strong(text="Response: ")
item += nodes.inline(text=text)
result.extend([addnodes.desc_content('', lst)])
return result
def parse_py_signature(signode, sig, desctype, env):
"""
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
classname, name, arglist = m.groups()
add_module = True
if env.currclass:
if classname and classname.startswith(env.currclass):
fullname = classname + name
# class name is given again in the signature
classname = classname[len(env.currclass):].lstrip('.')
add_module = False
elif classname:
# class name is given in the signature, but different
fullname = env.currclass + '.' + classname + name
else:
# class name is not given in the signature
fullname = env.currclass + '.' + name
add_module = False
else:
fullname = classname and classname + name or name
if classname:
signode += addnodes.desc_classname(classname, classname)
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
elif add_module and env.config.add_module_names and \
env.currmodule and env.currmodule != 'exceptions':
nodetext = env.currmodule + '.'
signode += addnodes.desc_classname(nodetext, nodetext)
signode += addnodes.desc_name(name, name)
if not arglist:
if desctype in ('function', 'method'):
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
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
return fullname, classname
def parse_py_signature(signode, sig, desctype, env):
"""
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
classname, name, arglist = m.groups()
add_module = True
if env.currclass:
if classname and classname.startswith(env.currclass):
fullname = classname + name
# class name is given again in the signature
classname = classname[len(env.currclass):].lstrip('.')
add_module = False
elif classname:
# class name is given in the signature, but different
fullname = env.currclass + '.' + classname + name
else:
# class name is not given in the signature
fullname = env.currclass + '.' + name
add_module = False
else:
fullname = classname and classname + name or name
if classname:
signode += addnodes.desc_classname(classname, classname)
# exceptions are a special case, since they are documented in the
# 'exceptions' module.
elif add_module and env.config.add_module_names and \
env.currmodule and env.currmodule != 'exceptions':
nodetext = env.currmodule + '.'
signode += addnodes.desc_classname(nodetext, nodetext)
signode += addnodes.desc_name(name, name)
if not arglist:
if desctype in ('function', 'method'):
# for callables, add an empty parameter list
signode += addnodes.desc_parameterlist()
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
return fullname, classname