python类desc_annotation()的实例源码

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

        # Add the "@" prefix
        if ("decorator" in self.options
                or self.objtype in ["decorator", "decoratormethod"]):
            signode.insert(0, addnodes.desc_addname("@", "@"))

        # Now that the "@" has been taken care of, we can add in the regular
        # prefix.
        prefix = self._get_signature_prefix()
        if prefix:
            signode.insert(0, addnodes.desc_annotation(prefix, prefix))

        # And here's the suffix:
        for optname in ["with", "async-with"]:
            if self.options.get(optname, "").strip():
                # for some reason a regular space here gets stripped, so we
                # use U+00A0 NO-BREAK SPACE
                s = "\u00A0as {}".format(self.options[optname])
                signode += addnodes.desc_annotation(s, s)

        return ret

def describe_signature(self, modifiers):
        def _add(modifiers, text):
            if len(modifiers) > 0:
                modifiers.append(nodes.Text(' '))
            modifiers.append(addnodes.desc_annotation(text, text))
        if self.storage:
            _add(modifiers, self.storage)
        if self.inline:
            _add(modifiers, 'inline')
        if self.virtual:
            _add(modifiers, 'virtual')
        if self.explicit:
            _add(modifiers, 'explicit')
        if self.constexpr:
            _add(modifiers, 'constexpr')
        if self.volatile:
            _add(modifiers, 'volatile')
        if self.const:
            _add(modifiers, 'const')

def handle_signature(self, sig, signode):
        if sig != 'Configuration':
            # Add "component" to the beginning if it's a specific component
            signode.clear()

            # Add "component" which is the type of this thing
            signode += addnodes.desc_annotation('component ', 'component ')

            if '.' in sig:
                modname, clsname = sig.rsplit('.', 1)
            else:
                modname, clsname = '', sig

            # If there's a module name, then we add the module
            if modname:
                signode += addnodes.desc_addname(modname + '.', modname + '.')

            # Add the class name
            signode += addnodes.desc_name(clsname, clsname)
        else:
            # Add just "Configuration"
            signode += addnodes.desc_name(sig, sig)

        return sig

def handle_signature(self, sig, signode):
        path = self.get_display_path()
        signode['is_multiline'] = True
        line = addnodes.desc_signature_line()
        line['add_permalink'] = True
        for x in path:
            line += addnodes.desc_addname(x + '.', x + '.')
        line += addnodes.desc_name(sig, sig)
        if 'required' in self.options:
            line += addnodes.desc_annotation(' (required)', ' (required)')
        signode += line
        if 'default' in self.options:
            line = addnodes.desc_signature_line()
            line += addnodes.desc_type('Default: ', 'Default: ')
            line += nodes.literal(self.options['default'],
                                  self.options['default'])
            signode += line
        return sig

def handle_signature(self, sig, signode):
        if 'hidden' in self.options:
            return sig
        path = self.get_display_path()
        signode['is_multiline'] = True
        line = addnodes.desc_signature_line()
        line['add_permalink'] = True
        for x in path:
            line += addnodes.desc_addname(x + '.', x + '.')
        line += addnodes.desc_name(sig, sig)
        if 'required' in self.options:
            line += addnodes.desc_annotation(' (required)', ' (required)')
        signode += line
        if 'default' in self.options:
            line = addnodes.desc_signature_line()
            line += addnodes.desc_type('Default: ', 'Default: ')
            line += nodes.literal(self.options['default'],
                                  self.options['default'])
            signode += line
        return sig

def handle_signature(self, sig, signode):
        if 'hidden' in self.options:
            return sig
        path = self.get_display_path()
        for x in path:
            signode += addnodes.desc_addname(x + '.', x + '.')
        signode += addnodes.desc_name(sig, sig)
        if 'type' in self.options:
            t = ' (%s)' % self.options['type']
            signode += addnodes.desc_annotation(t, t)
        return sig


######################################################################
#
# Autodoc directives
#

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

def describe_signature(self, signode, mode, env, parentScope):
        if self.prefix:
            signode += addnodes.desc_annotation(self.prefix, self.prefix)
            signode += nodes.Text(' ')
        self.nestedName.describe_signature(signode, mode, env,
                                           parentScope=parentScope)

def describe_signature(self, signode, mode, env, parentScope):
        _verify_description_mode(mode)
        paramlist = addnodes.desc_parameterlist()
        for arg in self.args:
            param = addnodes.desc_parameter('', '', noemph=True)
            if mode == 'lastIsName':  # i.e., outer-function params
                arg.describe_signature(param, 'param', env,
                                       parentScope=parentScope)
            else:
                arg.describe_signature(param, 'markType', env,
                                       parentScope=parentScope)
            paramlist += param
        signode += paramlist

        def _add_anno(signode, text):
            signode += nodes.Text(' ')
            signode += addnodes.desc_annotation(text, text)

        def _add_text(signode, text):
            signode += nodes.Text(' ' + text)

        if self.volatile:
            _add_anno(signode, 'volatile')
        if self.const:
            _add_anno(signode, 'const')
        if self.refQual:
            _add_text(signode, self.refQual)
        if self.exceptionSpec:
            _add_anno(signode, text_type(self.exceptionSpec))
        if self.final:
            _add_anno(signode, 'final')
        if self.override:
            _add_anno(signode, 'override')
        if self.initializer:
            _add_text(signode, '= ' + text_type(self.initializer))

def describe_signature(self, signode, mode, env, parentScope):
        _verify_description_mode(mode)
        modifiers = []

        def _add(modifiers, text):
            if len(modifiers) > 0:
                modifiers.append(nodes.Text(' '))
            modifiers.append(addnodes.desc_annotation(text, text))

        if self._print_visibility():
            _add(modifiers, self.visibility)
        self.leftSpecs.describe_signature(modifiers)

        for m in modifiers:
            signode += m
        if self.trailingTypeSpec:
            if len(modifiers) > 0:
                signode += nodes.Text(' ')
            self.trailingTypeSpec.describe_signature(signode, mode, env,
                                                     parentScope=parentScope)
            modifiers = []
            self.rightSpecs.describe_signature(modifiers)
            if len(modifiers) > 0:
                signode += nodes.Text(' ')
            for m in modifiers:
                signode += m

def describe_signature(self, signode, mode, env, parentScope):
        _verify_description_mode(mode)
        if self.visibility != 'public':
            signode += addnodes.desc_annotation(
                self.visibility, self.visibility)
            signode += nodes.Text(' ')
        self.name.describe_signature(signode, mode, env,
                                     parentScope=parentScope)
        if len(self.bases) > 0:
            signode += nodes.Text(' : ')
            for b in self.bases:
                b.describe_signature(signode, mode, env,
                                     parentScope=parentScope)
                signode += nodes.Text(', ')
            signode.pop()

def describe_signature(self, signode, mode, env, parentScope):
        _verify_description_mode(mode)
        # self.scoped has been done by the CPPEnumObject
        if self.visibility != 'public':
            signode += addnodes.desc_annotation(
                self.visibility, self.visibility)
            signode += nodes.Text(' ')
        self.name.describe_signature(signode, mode, env,
                                     parentScope=parentScope)
        if self.underlyingType:
            signode += nodes.Text(' : ')
            self.underlyingType.describe_signature(signode, 'noneIsName', env,
                                                   parentScope=parentScope)

def describe_signature(self, signode, ast, parentScope):
        signode += addnodes.desc_annotation('type ', 'type ')
        ast.describe_signature(signode, 'lastIsName', self.env,
                               parentScope=parentScope)

def describe_signature(self, signode, ast, parentScope):
        signode += addnodes.desc_annotation('class ', 'class ')
        ast.describe_signature(signode, 'lastIsName', self.env,
                               parentScope=parentScope)

def describe_signature(self, signode, ast, parentScope):
        prefix = 'enum '
        if ast.scoped:
            prefix += ast.scoped
            prefix += ' '
        signode += addnodes.desc_annotation(prefix, prefix)
        ast.describe_signature(signode, 'lastIsName', self.env,
                               parentScope=parentScope)

def handle_signature(self, signature, signode):
        """Prefix signature with the proper annotation, then render it using
        _render_signature.

        :returns: the name given to the resulting node, if any
        """
        if self.annotation:
            annotation = self.annotation + ' '
            signode += addnodes.desc_annotation(annotation, annotation)
        self._render_signature(signature, signode)
        return self._name_from_signature(signature)

def handle_signature(self, sig, signode):
        assert (not sig.startswith('<<')) and (not sig.endswith('>>'))
        modname = self.options.get(
            'module', self.env.ref_context.get('py:module'))
        classname = self.env.ref_context.get('py:class')
        fullname = classname + '.' + sig

        signode['module'] = modname
        signode['class'] = classname
        signode['fullname'] = fullname

        signode += desc_annotation('virtual event ', 'virtual event ')
        signode += desc_name('<<' + sig + '>>', '<<' + sig + '>>')

        return fullname, ''

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

def process_mongomotor_nodes(app, doctree):
    # Search doctree for MongoMotor's methods and attributes whose docstrings
    #  were copied from MongoEngine, and fix them up for MongoMotor:
    #   1. Remove all version annotations like "New in version 2.0" since
    #      PyMongo's version numbers are meaningless in Motor's docs.
    #   2. 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', 'classmethod'):
            signature_node = find_by_path(objnode, [desc_signature])[0]
            name = '.'.join([
                signature_node['module'], signature_node['fullname']])

            assert name.startswith('mongomotor.')
            obj_mm_info = mm_info.get(name)
            if obj_mm_info:
                desc_content_node = find_by_path(objnode, [desc_content])[0]
                if (obj_mm_info.get('is_async_method') or
                        obj_mm_info.get('has_coroutine_annotation')):
                    coro_annotation = addnodes.desc_annotation(
                        'coroutine ', 'coroutine ',
                        classes=['coro-annotation'])
                    signature_node.insert(0, coro_annotation)

                if obj_mm_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 process_service(self, filename):
        data = self.get_json_from_file(os.path.join(self.dir, filename))
        request_filename = self.write_tmp(data['request'] or '')
        response_filename = self.write_tmp(data['response'] or '')

        example = HTTPExample(
            'http:example',
            arguments=['curl', 'httpie', 'python-requests'],
            options={
                'request': request_filename,
                'response': response_filename
            },
            content=self.content,
            lineno=self.lineno,
            content_offset=self.content_offset,
            block_text='.. http:example::',
            state=self.state,
            state_machine=self.state_machine
        )

        method = data['method'].upper()
        service = data['service']
        name = service.get('name') or ''
        path_scheme = data.get('path_scheme') or name
        summary = service.get('summary') or ''
        permission = service.get('permission') or ''

        container = nodes.container('')
        container.append(addnodes.desc_name('', method + ' '))
        container.append(addnodes.desc_name('', path_scheme))

        inner_container = nodes.definition('')
        container.append(inner_container)

        inner_container.append(nodes.paragraph(summary, summary))
        inner_container.append(addnodes.desc_name('permission', 'permission'))
        perm_label = ': ' + permission
        inner_container.append(addnodes.desc_annotation(perm_label, perm_label))
        inner_container.append(example.run()[0])

        # extra = nodes.paragraph('', '')
        # inner_container.append(extra)
        # if service.get('responses'):
        #     extra.append(nodes.strong('', 'Responses'))
        #     blist = nodes.bullet_list('')
        #     extra.append(blist)
        #     for code, config in service['responses'].items():
        #         blist.append(render_response(code, 'Hello'))

        # cleanup
        os.remove(request_filename)
        os.remove(response_filename)

        return container

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.ref_context.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)
        return fullname, nameprefix

def process_mongomotor_nodes(app, doctree):
    # Search doctree for MongoMotor's methods and attributes whose docstrings
    #  were copied from MongoEngine, and fix them up for MongoMotor:
    #   1. Remove all version annotations like "New in version 2.0" since
    #      PyMongo's version numbers are meaningless in Motor's docs.
    #   2. 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', 'classmethod'):
            signature_node = find_by_path(objnode, [desc_signature])[0]
            name = '.'.join([
                signature_node['module'], signature_node['fullname']])

            assert name.startswith('mongomotor.')
            obj_mm_info = mm_info.get(name)
            if obj_mm_info:
                desc_content_node = find_by_path(objnode, [desc_content])[0]
                if (obj_mm_info.get('is_async_method') or
                        obj_mm_info.get('has_coroutine_annotation')):
                    coro_annotation = addnodes.desc_annotation(
                        'coroutine ', 'coroutine ',
                        classes=['coro-annotation'])
                    signature_node.insert(0, coro_annotation)

                if obj_mm_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)