Python sphinx.addnodes.desc_annotation() Examples

def handle_signature(self,sig,signode):
    sig = sig.strip()
    type_name, name, arglist = protobuf_sig_regex.match(sig).groups()

    if self.prefix:
      signode += addnodes.desc_annotation(self.prefix+' ', self.prefix+' ')

    if type_name:
      signode += addnodes.desc_type(type_name, type_name)

    if name:
      signode += addnodes.desc_name(name,name)

    if arglist:
      paramlist = addnodes.desc_parameterlist()
      for arg in arglist.split(','):
        argtype, argname = arg.split(None,1)
        param = addnodes.desc_parameter(noemph=True)
        param += nodes.Text(argtype,argtype)
        param += nodes.emphasis(' '+argname,' '+argname)
        paramlist += param
      signode += paramlist

    return name 

def handle_signature(self, sig, signode):
        if '::' in sig:
            mod, name = sig.strip().split('::')
        else:
            name = sig.strip()
            mod = 'std'

        display = name.replace('-', ' ')
        if mod != 'std':
            display = f'{mod}::{display}'

        signode['eql-module'] = mod
        signode['eql-name'] = name
        signode['eql-fullname'] = fullname = f'{mod}::{name}'

        signode += s_nodes.desc_annotation('type', 'type')
        signode += d_nodes.Text(' ')
        signode += s_nodes.desc_name(display, display)
        return fullname 

def handle_signature(self, sig, signode):
        modifiers, typ, params, getter, setter = parse_indexer_signature(sig)
        self.append_modifiers(signode, modifiers)
        self.append_type(signode, typ)
        signode += nodes.Text(' ')
        signode += addnodes.desc_name('this[]', 'this')
        self.append_indexer_parameters(signode, params)
        signode += nodes.Text(' { ')
        extra = []
        if getter:
            extra.append('get;')
        if setter:
            extra.append('set;')
        extra_str = ' '.join(extra)
        signode += addnodes.desc_annotation(extra_str, extra_str)
        signode += nodes.Text(' }')
        return self.get_fullname('this[]') 

def handle_signature(self, sig, signode):
        modifiers, typ, name, getter, setter = parse_property_signature(sig)
        self.append_modifiers(signode, modifiers)
        self.append_type(signode, typ)
        signode += nodes.Text(' ')
        signode += addnodes.desc_name(name, name)
        signode += nodes.Text(' { ')
        extra = []
        if getter:
            extra.append('get;')
        if setter:
            extra.append('set;')
        extra_str = ' '.join(extra)
        signode += addnodes.desc_annotation(extra_str, extra_str)
        signode += nodes.Text(' }')
        return self.get_fullname(name) 

def handle_signature(self, sig, signode):
        name = sig
        config = self.options.get('config', self.env.ref_context.get('cfg:config', ""))
        if not config:
            logger.warning("config option with unknown config", location=signode)
            config = "UNKNOWN"
        fullname = config + '.' + name

        signode += addnodes.desc_annotation('option ', 'option ')
        if not self.env.ref_context.get('cfg:in-config', False):
            signode += addnodes.pending_xref(sig,
                                             addnodes.desc_addname(config, config),
                                             refdomain='cfg',
                                             reftype='config',
                                             reftarget=config)
            signode += addnodes.desc_addname('', '.')

        signode += addnodes.desc_name(sig, '', nodes.Text(sig))

        typ = self.options.get('type')
        if typ:
            type_node = addnodes.desc_annotation(': ', ': ')
            info = self.content.parent.info(1)  # might be off by a few lines...
            type_node.extend(_parse_inline(self.state, typ, info))
            signode += type_node

        defaultvalue = self.options.get('default')
        if defaultvalue:
            val_node = addnodes.desc_annotation(' = ', ' = ')
            val_node += nodes.literal(defaultvalue, defaultvalue)
            signode += val_node

        return fullname, config 

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):
        ret = super().handle_signature(sig, signode)
        signode.insert(0, addnodes.desc_annotation("coroutine ", "coroutine "))
        return ret 

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):
        signode += addnodes.desc_annotation('REST type ', 'REST type ')
        signode += addnodes.desc_name(sig, sig) 

def handle_signature(self, sig, signode):
        ret = super(PyCoroutineMixin, self).handle_signature(sig, signode)
        signode.insert(0, addnodes.desc_annotation('coroutine ', 'coroutine '))
        return ret 

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):
        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 handle_signature(self, sig, signode):
        if self.names:
            name = self.names[0]
        else:
            try:
                name, sig = sig.split(':', 1)
            except Exception as ex:
                raise shared.DirectiveParseError(
                    self,
                    f':eql:operator signature must match "NAME: SIGNATURE" '
                    f'template',
                    cause=ex)
            name = name.strip()

        sig = sig.strip()
        if not name or not sig:
            raise shared.DirectiveParseError(
                self, f'invalid :eql:operator: signature')

        signode['eql-name'] = name
        signode['eql-fullname'] = name
        signode['eql-signature'] = sig

        signode += s_nodes.desc_annotation('operator', 'operator')
        signode += d_nodes.Text(' ')
        signode += s_nodes.desc_name(sig, sig)

        return name 

def handle_signature(self, sig, signode):
        signode['eql-name'] = sig
        signode['eql-fullname'] = sig

        display = sig.replace('-', ' ')
        signode += s_nodes.desc_annotation('keyword', 'keyword')
        signode += d_nodes.Text(' ')
        signode += s_nodes.desc_name(display, display)

        return sig 

def handle_signature(self, sig, signode):
        fullname, prefix = super().handle_signature(sig, signode)

        if 'staticmethod' in self.options:
            signode.insert(
                0, s_nodes.desc_annotation('static method', 'static method'))

        return fullname, prefix 

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):
        fullname = sig
        signode += addnodes.desc_annotation('config ', 'config ')
        signode += addnodes.desc_name(sig, '', nodes.Text(sig))
        return fullname 

def handle_signature(self, sig, signode):
        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.SET_OF:
            ret_repr = f'SET OF {ret_repr}'
        elif astnode.returning_typemod is qltypes.TypeModifier.OPTIONAL:
            ret_repr = f'OPTIONAL {ret_repr}'
        signode += s_nodes.desc_returns(ret_repr, ret_repr)

        return fullname 

def make_process_header(self, slug, typ, version, source_uri, description, inputs):
        """Generate a process definition header.

        :param str slug: process' slug
        :param str typ: process' type
        :param str version:  process' version
        :param str source_uri: url to the process definition
        :param str description: process' description
        :param dict inputs: process' inputs

        """
        node = addnodes.desc()
        signode = addnodes.desc_signature(slug, "")
        node.append(signode)

        node["objtype"] = node["desctype"] = typ

        signode += addnodes.desc_annotation(typ, typ, classes=["process-type"])
        signode += addnodes.desc_addname("", "")
        signode += addnodes.desc_name(slug + " ", slug + " ")

        paramlist = addnodes.desc_parameterlist()

        for field_schema, _, _ in iterate_schema({}, inputs, ""):
            field_type = field_schema["type"]
            field_name = field_schema["name"]

            field_default = field_schema.get("default", None)
            field_default = "" if field_default is None else "={}".format(field_default)

            param = addnodes.desc_parameter("", "", noemph=True)
            param += nodes.emphasis(field_type, field_type, classes=["process-type"])
            # separate by non-breaking space in the output
            param += nodes.strong(text="\xa0\xa0" + field_name)

            paramlist += param

        signode += paramlist
        signode += nodes.reference(
            "",
            nodes.Text("[Source: v{}]".format(version)),
            refuri=source_uri,
            classes=["viewcode-link"],
        )

        desc = nodes.paragraph()
        desc += nodes.Text(description, description)

        return [node, desc]