def setUp(self): super(TestTraverseAndDocumentShape, self).setUp() self.add_shape_to_params('Foo', 'String', 'This describes foo.') self.event_emitter = mock.Mock() self.request_example = RequestExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter) self.response_example = ResponseExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter)
class TestTraverseAndDocumentShape(BaseExampleDocumenterTest): def setUp(self): super(TestTraverseAndDocumentShape, self).setUp() self.add_shape_to_params('Foo', 'String', 'This describes foo.') self.event_emitter = mock.Mock() self.request_example = RequestExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter) self.response_example = ResponseExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter) def test_events_emitted_response_example(self): self.response_example.traverse_and_document_shape( section=self.doc_structure, shape=self.operation_model.input_shape, history=[]) structure_section = self.doc_structure.get_section('structure-value') print(self.event_emitter.emit.call_args_list[0][1]['section'].name) self.assertEqual(self.event_emitter.emit.call_args_list, [ mock.call('docs.response-example.myservice.SampleOperation.Foo', section=structure_section.get_section('Foo').get_section( 'member-value')), mock.call(('docs.response-example.myservice.SampleOperation' '.complete-section'), section=self.doc_structure) ]) def test_events_emitted_request_example(self): self.request_example.traverse_and_document_shape( section=self.doc_structure, shape=self.operation_model.input_shape, history=[]) structure_section = self.doc_structure.get_section('structure-value') self.assertEqual(self.event_emitter.emit.call_args_list, [ mock.call('docs.request-example.myservice.SampleOperation.Foo', section=structure_section.get_section('Foo').get_section( 'member-value')), mock.call(('docs.request-example.myservice.SampleOperation' '.complete-section'), section=self.doc_structure) ])
class TestTraverseAndDocumentShape(BaseExampleDocumenterTest): def setUp(self): super(TestTraverseAndDocumentShape, self).setUp() self.add_shape_to_params('Foo', 'String', 'This describes foo.') self.event_emitter = mock.Mock() self.request_example = RequestExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter) self.response_example = ResponseExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter) def test_events_emitted_response_example(self): self.response_example.traverse_and_document_shape( section=self.doc_structure, shape=self.operation_model.input_shape, history=[] ) structure_section = self.doc_structure.get_section('structure-value') print(self.event_emitter.emit.call_args_list[0][1]['section'].name) self.assertEqual( self.event_emitter.emit.call_args_list, [mock.call('docs.response-example.myservice.SampleOperation.Foo', section=structure_section.get_section( 'Foo').get_section('member-value')), mock.call(('docs.response-example.myservice.SampleOperation' '.complete-section'), section=self.doc_structure)] ) def test_events_emitted_request_example(self): self.request_example.traverse_and_document_shape( section=self.doc_structure, shape=self.operation_model.input_shape, history=[] ) structure_section = self.doc_structure.get_section('structure-value') self.assertEqual( self.event_emitter.emit.call_args_list, [mock.call('docs.request-example.myservice.SampleOperation.Foo', section=structure_section.get_section( 'Foo').get_section('member-value')), mock.call(('docs.request-example.myservice.SampleOperation' '.complete-section'), section=self.doc_structure)] )
def test_alias_parameter_in_documentation_request_example(self): RequestExampleDocumenter('myservice', 'myoperation', self.event_emitter).document_example( self.sample_section, self.operation_model.input_shape) self.parameter_alias.alias_parameter_in_documentation( 'docs.request-example.myservice.myoperation.complete-section', self.sample_section) contents = self.sample_section.flush_structure().decode('utf-8') self.assertIn(self.alias_name + '=', contents) self.assertNotIn(self.original_name + '=', contents)
def setUp(self): super(BaseExampleDocumenterTest, self).setUp() self.event_emitter = HierarchicalEmitter() self.request_example = RequestExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter) self.response_example = ResponseExampleDocumenter( service_name='myservice', operation_name='SampleOperation', event_emitter=self.event_emitter)
def document_model_driven_method(section, method_name, operation_model, event_emitter, method_description=None, example_prefix=None, include_input=None, include_output=None, exclude_input=None, exclude_output=None, document_output=True, include_signature=True): """Documents an individual method :param section: The section to write to :param method_name: The name of the method :param operation_model: The model of the operation :param event_emitter: The event emitter to use to emit events :param example_prefix: The prefix to use in the method example. :type include_input: Dictionary where keys are parameter names and values are the shapes of the parameter names. :param include_input: The parameter shapes to include in the input documentation. :type include_output: Dictionary where keys are parameter names and values are the shapes of the parameter names. :param include_input: The parameter shapes to include in the output documentation. :type exclude_input: List of the names of the parameters to exclude. :param exclude_input: The names of the parameters to exclude from input documentation. :type exclude_output: List of the names of the parameters to exclude. :param exclude_input: The names of the parameters to exclude from output documentation. :param document_output: A boolean flag to indicate whether to document the output. :param include_signature: Whether or not to include the signature. It is useful for generating docstrings. """ # Add the signature if specified. if include_signature: document_model_driven_signature(section, method_name, operation_model, include=include_input, exclude=exclude_input) # Add the description for the method. method_intro_section = section.add_new_section('method-intro') method_intro_section.include_doc_string(method_description) # Add the example section. example_section = section.add_new_section('example') example_section.style.new_paragraph() example_section.style.bold('Request Syntax') context = { 'special_shape_types': { 'streaming_input_shape': operation_model.get_streaming_input(), 'streaming_output_shape': operation_model.get_streaming_output() } } if operation_model.input_shape: RequestExampleDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_example(example_section, operation_model.input_shape, prefix=example_prefix, include=include_input, exclude=exclude_input) else: example_section.style.new_paragraph() example_section.style.start_codeblock() example_section.write(example_prefix + '()') # Add the request parameter documentation. request_params_section = section.add_new_section('request-params') if operation_model.input_shape: RequestParamsDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_params(request_params_section, operation_model.input_shape, include=include_input, exclude=exclude_input) # Add the return value documentation return_section = section.add_new_section('return') return_section.style.new_line() if operation_model.output_shape is not None and document_output: return_section.write(':rtype: dict') return_section.style.new_line() return_section.write(':returns: ') return_section.style.indent() return_section.style.new_line() # Add an example return value return_example_section = return_section.add_new_section('example') return_example_section.style.new_line() return_example_section.style.bold('Response Syntax') return_example_section.style.new_paragraph() ResponseExampleDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_example(return_example_section, operation_model.output_shape, include=include_output, exclude=exclude_output) # Add a description for the return value return_description_section = return_section.add_new_section( 'description') return_description_section.style.new_line() return_description_section.style.bold('Response Structure') return_description_section.style.new_paragraph() ResponseParamsDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_params(return_description_section, operation_model.output_shape, include=include_output, exclude=exclude_output) else: return_section.write(':returns: None')
def document_model_driven_method(section, method_name, operation_model, event_emitter, method_description=None, example_prefix=None, include_input=None, include_output=None, exclude_input=None, exclude_output=None, document_output=True, include_signature=True): """Documents an individual method :param section: The section to write to :param method_name: The name of the method :param operation_model: The model of the operation :param event_emitter: The event emitter to use to emit events :param example_prefix: The prefix to use in the method example. :type include_input: Dictionary where keys are parameter names and values are the shapes of the parameter names. :param include_input: The parameter shapes to include in the input documentation. :type include_output: Dictionary where keys are parameter names and values are the shapes of the parameter names. :param include_input: The parameter shapes to include in the output documentation. :type exclude_input: List of the names of the parameters to exclude. :param exclude_input: The names of the parameters to exclude from input documentation. :type exclude_output: List of the names of the parameters to exclude. :param exclude_input: The names of the parameters to exclude from output documentation. :param document_output: A boolean flag to indicate whether to document the output. :param include_signature: Whether or not to include the signature. It is useful for generating docstrings. """ # Add the signature if specified. if include_signature: document_model_driven_signature(section, method_name, operation_model, include=include_input, exclude=exclude_input) # Add the description for the method. method_intro_section = section.add_new_section('method-intro') method_intro_section.include_doc_string(method_description) if operation_model.deprecated: method_intro_section.style.start_danger() method_intro_section.writeln( 'This operation is deprecated and may not function as ' 'expected. This operation should not be used going forward ' 'and is only kept for the purpose of backwards compatiblity.') method_intro_section.style.end_danger() service_uid = operation_model.service_model.metadata.get('uid') if service_uid is not None: method_intro_section.style.new_paragraph() method_intro_section.write("See also: ") link = '%s/%s/%s' % (AWS_DOC_BASE, service_uid, operation_model.name) method_intro_section.style.external_link(title="AWS API Documentation", link=link) method_intro_section.writeln('') # Add the example section. example_section = section.add_new_section('example') example_section.style.new_paragraph() example_section.style.bold('Request Syntax') context = { 'special_shape_types': { 'streaming_input_shape': operation_model.get_streaming_input(), 'streaming_output_shape': operation_model.get_streaming_output(), 'eventstream_output_shape': operation_model.get_event_stream_output(), }, } if operation_model.input_shape: RequestExampleDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_example(example_section, operation_model.input_shape, prefix=example_prefix, include=include_input, exclude=exclude_input) else: example_section.style.new_paragraph() example_section.style.start_codeblock() example_section.write(example_prefix + '()') # Add the request parameter documentation. request_params_section = section.add_new_section('request-params') if operation_model.input_shape: RequestParamsDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_params(request_params_section, operation_model.input_shape, include=include_input, exclude=exclude_input) # Add the return value documentation return_section = section.add_new_section('return') return_section.style.new_line() if operation_model.output_shape is not None and document_output: return_section.write(':rtype: dict') return_section.style.new_line() return_section.write(':returns: ') return_section.style.indent() return_section.style.new_line() # If the operation is an event stream, describe the tagged union event_stream_output = operation_model.get_event_stream_output() if event_stream_output: event_section = return_section.add_new_section('event-stream') event_section.style.new_paragraph() event_section.write( 'The response of this operation contains an ' ':class:`.EventStream` member. When iterated the ' ':class:`.EventStream` will yield events based on the ' 'structure below, where only one of the top level keys ' 'will be present for any given event.') event_section.style.new_line() # Add an example return value return_example_section = return_section.add_new_section('example') return_example_section.style.new_line() return_example_section.style.bold('Response Syntax') return_example_section.style.new_paragraph() ResponseExampleDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_example(return_example_section, operation_model.output_shape, include=include_output, exclude=exclude_output) # Add a description for the return value return_description_section = return_section.add_new_section( 'description') return_description_section.style.new_line() return_description_section.style.bold('Response Structure') return_description_section.style.new_paragraph() ResponseParamsDocumenter( service_name=operation_model.service_model.service_name, operation_name=operation_model.name, event_emitter=event_emitter, context=context).document_params(return_description_section, operation_model.output_shape, include=include_output, exclude=exclude_output) else: return_section.write(':returns: None')