Exemple #1
0
    def _document_sub_resource(self, sub_resource_section, sub_resource):
        identifiers_needed = []
        for identifier in sub_resource.resource.identifiers:
            if identifier.source == 'input':
                identifiers_needed.append(xform_name(identifier.target))

        signature_args = get_identifier_args_for_signature(identifiers_needed)
        sub_resource_section.style.start_sphinx_py_method(
            sub_resource.name, signature_args)

        method_intro_section = sub_resource_section.add_new_section(
            'method-intro')
        description = 'Creates a %s resource.' % sub_resource.resource.type
        method_intro_section.include_doc_string(description)

        example_section = sub_resource_section.add_new_section('example')
        example_values = get_identifier_values_for_example(identifiers_needed)
        resource_name = xform_name(self._resource_name)
        if self.represents_service_resource:
            resource_name = self._resource_name
        example = '%s = %s.%s(%s)' % (
            xform_name(sub_resource.resource.type),
            resource_name,
            sub_resource.name, example_values
        )
        example_section.style.start_codeblock()
        example_section.write(example)
        example_section.style.end_codeblock()

        param_section = sub_resource_section.add_new_section('params')
        for identifier in identifiers_needed:
            description = get_identifier_description(
                sub_resource.name, identifier)
            param_section.write(':type %s: string' % identifier)
            param_section.style.new_line()
            param_section.write(':param %s: %s' % (
                identifier, description))
            param_section.style.new_line()

        return_section = sub_resource_section.add_new_section('return')
        return_section.style.new_line()
        return_section.write(
            ':rtype: :py:class:`%s.%s`' % (
                self._service_docs_name, sub_resource.resource.type))
        return_section.style.new_line()
        return_section.write(
            ':returns: A %s resource' % sub_resource.resource.type)
        return_section.style.new_line()
Exemple #2
0
    def _document_sub_resource(self, sub_resource_section, sub_resource):
        identifiers_needed = []
        for identifier in sub_resource.resource.identifiers:
            if identifier.source == 'input':
                identifiers_needed.append(xform_name(identifier.target))

        signature_args = get_identifier_args_for_signature(identifiers_needed)
        sub_resource_section.style.start_sphinx_py_method(
            sub_resource.name, signature_args)

        method_intro_section = sub_resource_section.add_new_section(
            'method-intro')
        description = 'Creates a %s resource.' % sub_resource.resource.type
        method_intro_section.include_doc_string(description)

        example_section = sub_resource_section.add_new_section('example')
        example_values = get_identifier_values_for_example(identifiers_needed)
        resource_name = xform_name(self._resource_name)
        if self.represents_service_resource:
            resource_name = self._resource_name
        example = '%s = %s.%s(%s)' % (xform_name(
            sub_resource.resource.type), resource_name, sub_resource.name,
                                      example_values)
        example_section.style.start_codeblock()
        example_section.write(example)
        example_section.style.end_codeblock()

        param_section = sub_resource_section.add_new_section('params')
        for identifier in identifiers_needed:
            description = get_identifier_description(sub_resource.name,
                                                     identifier)
            param_section.write(':type %s: string' % identifier)
            param_section.style.new_line()
            param_section.write(':param %s: %s' % (identifier, description))
            param_section.style.new_line()

        return_section = sub_resource_section.add_new_section('return')
        return_section.style.new_line()
        return_section.write(
            ':rtype: :py:class:`%s.%s`' %
            (self._service_docs_name, sub_resource.resource.type))
        return_section.style.new_line()
        return_section.write(':returns: A %s resource' %
                             sub_resource.resource.type)
        return_section.style.new_line()
Exemple #3
0
    def _add_intro(self, section):
        identifier_names = []
        if self._resource_model.identifiers:
            for identifier in self._resource_model.identifiers:
                identifier_names.append(identifier.name)

        # Write out the class signature.
        class_args = get_identifier_args_for_signature(identifier_names)
        section.style.start_sphinx_py_class(class_name="%s(%s)" % (self.class_name, class_args))

        # Add as short description about the resource
        description_section = section.add_new_section("description")
        self._add_description(description_section)

        # Add an example of how to instantiate the resource
        example_section = section.add_new_section("example")
        self._add_example(example_section, identifier_names)

        # Add the description for the parameters to instantiate the
        # resource.
        param_section = section.add_new_section("params")
        self._add_params_description(param_section, identifier_names)
Exemple #4
0
    def _add_intro(self, section):
        identifier_names = []
        if self._resource_model.identifiers:
            for identifier in self._resource_model.identifiers:
                identifier_names.append(identifier.name)

        # Write out the class signature.
        class_args = get_identifier_args_for_signature(identifier_names)
        section.style.start_sphinx_py_class(class_name='%s(%s)' %
                                            (self.class_name, class_args))

        # Add as short description about the resource
        description_section = section.add_new_section('description')
        self._add_description(description_section)

        # Add an example of how to instantiate the resource
        example_section = section.add_new_section('example')
        self._add_example(example_section, identifier_names)

        # Add the description for the parameters to instantiate the
        # resource.
        param_section = section.add_new_section('params')
        self._add_params_description(param_section, identifier_names)
Exemple #5
0
def document_sub_resource(section,
                          resource_name,
                          sub_resource_model,
                          service_model,
                          include_signature=True):
    """Documents a resource action

    :param section: The section to write to

    :param resource_name: The name of the resource

    :param sub_resource_model: The model of the subresource

    :param service_model: The model of the service

    :param include_signature: Whether or not to include the signature.
        It is useful for generating docstrings.
    """
    identifiers_needed = []
    for identifier in sub_resource_model.resource.identifiers:
        if identifier.source == 'input':
            identifiers_needed.append(xform_name(identifier.target))

    if include_signature:
        signature_args = get_identifier_args_for_signature(identifiers_needed)
        section.style.start_sphinx_py_method(sub_resource_model.name,
                                             signature_args)

    method_intro_section = section.add_new_section('method-intro')
    description = 'Creates a %s resource.' % sub_resource_model.resource.type
    method_intro_section.include_doc_string(description)
    example_section = section.add_new_section('example')
    example_values = get_identifier_values_for_example(identifiers_needed)
    example_resource_name = xform_name(resource_name)
    if service_model.service_name == resource_name:
        example_resource_name = resource_name
    example = '%s = %s.%s(%s)' % (xform_name(
        sub_resource_model.resource.type), example_resource_name,
                                  sub_resource_model.name, example_values)
    example_section.style.start_codeblock()
    example_section.write(example)
    example_section.style.end_codeblock()

    param_section = section.add_new_section('params')
    for identifier in identifiers_needed:
        description = get_identifier_description(sub_resource_model.name,
                                                 identifier)
        param_section.write(':type %s: string' % identifier)
        param_section.style.new_line()
        param_section.write(':param %s: %s' % (identifier, description))
        param_section.style.new_line()

    return_section = section.add_new_section('return')
    return_section.style.new_line()
    return_section.write(':rtype: :py:class:`%s.%s`' %
                         (get_service_module_name(service_model),
                          sub_resource_model.resource.type))
    return_section.style.new_line()
    return_section.write(':returns: A %s resource' %
                         sub_resource_model.resource.type)
    return_section.style.new_line()
Exemple #6
0
def document_sub_resource(section, resource_name, sub_resource_model,
                          service_model, include_signature=True):
    """Documents a resource action

    :param section: The section to write to

    :param resource_name: The name of the resource

    :param sub_resource_model: The model of the subresource

    :param service_model: The model of the service

    :param include_signature: Whether or not to include the signature.
        It is useful for generating docstrings.
    """
    identifiers_needed = []
    for identifier in sub_resource_model.resource.identifiers:
        if identifier.source == 'input':
            identifiers_needed.append(xform_name(identifier.target))

    if include_signature:
        signature_args = get_identifier_args_for_signature(identifiers_needed)
        section.style.start_sphinx_py_method(
            sub_resource_model.name, signature_args)

    method_intro_section = section.add_new_section(
        'method-intro')
    description = 'Creates a %s resource.' % sub_resource_model.resource.type
    method_intro_section.include_doc_string(description)
    example_section = section.add_new_section('example')
    example_values = get_identifier_values_for_example(identifiers_needed)
    example_resource_name = xform_name(resource_name)
    if service_model.service_name == resource_name:
        example_resource_name = resource_name
    example = '%s = %s.%s(%s)' % (
        xform_name(sub_resource_model.resource.type),
        example_resource_name,
        sub_resource_model.name, example_values
    )
    example_section.style.start_codeblock()
    example_section.write(example)
    example_section.style.end_codeblock()

    param_section = section.add_new_section('params')
    for identifier in identifiers_needed:
        description = get_identifier_description(
            sub_resource_model.name, identifier)
        param_section.write(':type %s: string' % identifier)
        param_section.style.new_line()
        param_section.write(':param %s: %s' % (
            identifier, description))
        param_section.style.new_line()

    return_section = section.add_new_section('return')
    return_section.style.new_line()
    return_section.write(
        ':rtype: :py:class:`%s.%s`' % (
            get_service_module_name(service_model),
            sub_resource_model.resource.type))
    return_section.style.new_line()
    return_section.write(
        ':returns: A %s resource' % sub_resource_model.resource.type)
    return_section.style.new_line()