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