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()
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()
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)
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)
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()
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()