def _create_docstring(self): docstring_structure = DocumentStructure('docstring', target='html') # Call the document method function with the args and kwargs # passed to the class. self._write_docstring(docstring_structure, *self._gen_args, **self._gen_kwargs) return docstring_structure.flush_structure().decode('utf-8')
def setUp(self): self.root_dir = tempfile.mkdtemp() self.version_dirs = os.path.join(self.root_dir, 'myservice', '2014-01-01') os.makedirs(self.version_dirs) self.model_file = os.path.join(self.version_dirs, 'service-2.json') self.waiter_model_file = os.path.join(self.version_dirs, 'waiters-2.json') self.paginator_model_file = os.path.join(self.version_dirs, 'paginators-1.json') self.resource_model_file = os.path.join(self.version_dirs, 'resources-1.json') self.example_model_file = os.path.join(self.version_dirs, 'examples-1.json') self.json_model = {} self.waiter_json_model = {} self.paginator_json_model = {} self.resource_json_model = {} self._setup_models() self.doc_name = 'MyDoc' self.doc_structure = DocumentStructure(self.doc_name) self.setup_client_and_resource()
def test_create_sections_at_instantiation(self): sections = ['intro', 'middle', 'end'] self.doc_structure = DocumentStructure(self.name, section_names=sections) # Ensure the sections are attached to the new document structure. for section_name in sections: section = self.doc_structure.get_section(section_name) self.assertEqual(section.name, section_name)
def setUp(self): self.original_name = 'original' self.alias_name = 'alias' self.parameter_alias = handlers.ParameterAlias( self.original_name, self.alias_name) self.operation_model = mock.Mock() request_shape = DenormalizedStructureBuilder().with_members( {self.original_name: {'type': 'string'}}).build_model() self.operation_model.input_shape = request_shape self.sample_section = DocumentStructure('') self.event_emitter = HierarchicalEmitter()
def document_service(self): """Documents an entire service. :returns: The reStructured text of the documented service. """ doc_structure = DocumentStructure(self._service_name, section_names=self.sections, target='html') self.title(doc_structure.get_section('title')) self.table_of_contents(doc_structure.get_section('table-of-contents')) self.client_api(doc_structure.get_section('client-api')) self.client_exceptions(doc_structure.get_section('client-exceptions')) self.paginator_api(doc_structure.get_section('paginator-api')) self.waiter_api(doc_structure.get_section('waiter-api')) return doc_structure.flush_structure()
def setUp(self): self.root_dir = tempfile.mkdtemp() self.version_dirs = os.path.join(self.root_dir, 'myservice', '2014-01-01') os.makedirs(self.version_dirs) self.model_file = os.path.join(self.version_dirs, 'service-2.json') self.waiter_model_file = os.path.join(self.version_dirs, 'waiters-2.json') self.paginator_model_file = os.path.join(self.version_dirs, 'paginators-1.json') self.example_model_file = os.path.join(self.version_dirs, 'examples-1.json') self.json_model = {} self.nested_json_model = {} self._setup_models() self.build_models() self.events = HierarchicalEmitter() self.setup_client() self.doc_name = 'MyDoc' self.doc_structure = DocumentStructure(self.doc_name, target='html')
class TestParameterAlias(unittest.TestCase): def setUp(self): self.original_name = 'original' self.alias_name = 'alias' self.parameter_alias = handlers.ParameterAlias( self.original_name, self.alias_name) self.operation_model = mock.Mock() request_shape = DenormalizedStructureBuilder().with_members( {self.original_name: {'type': 'string'}}).build_model() self.operation_model.input_shape = request_shape self.sample_section = DocumentStructure('') self.event_emitter = HierarchicalEmitter() def test_alias_parameter_in_call(self): value = 'value' params = {self.alias_name: value} self.parameter_alias.alias_parameter_in_call( params, self.operation_model) self.assertEqual(params, {self.original_name: value}) def test_alias_parameter_and_original_in_call(self): params = { self.original_name: 'orginal_value', self.alias_name: 'alias_value' } with self.assertRaises(AliasConflictParameterError): self.parameter_alias.alias_parameter_in_call( params, self.operation_model) def test_alias_parameter_in_call_does_not_touch_original(self): value = 'value' params = {self.original_name: value} self.parameter_alias.alias_parameter_in_call( params, self.operation_model) self.assertEqual(params, {self.original_name: value}) def test_does_not_alias_parameter_for_no_input_shape(self): value = 'value' params = {self.alias_name: value} self.operation_model.input_shape = None self.parameter_alias.alias_parameter_in_call( params, self.operation_model) self.assertEqual(params, {self.alias_name: value}) def test_does_not_alias_parameter_for_not_modeled_member(self): value = 'value' params = {self.alias_name: value} request_shape = DenormalizedStructureBuilder().with_members( {'foo': {'type': 'string'}}).build_model() self.operation_model.input_shape = request_shape self.parameter_alias.alias_parameter_in_call( params, self.operation_model) self.assertEqual(params, {self.alias_name: value}) def test_alias_parameter_in_documentation_request_params(self): RequestParamsDocumenter( 'myservice', 'myoperation', self.event_emitter).document_params( self.sample_section, self.operation_model.input_shape) self.parameter_alias.alias_parameter_in_documentation( 'docs.request-params.myservice.myoperation.complete-section', self.sample_section ) contents = self.sample_section.flush_structure().decode('utf-8') self.assertIn(':type ' + self.alias_name + ':', contents) self.assertIn(':param ' + self.alias_name + ':', contents) self.assertNotIn(':type ' + self.original_name + ':', contents) self.assertNotIn(':param ' + self.original_name + ':', contents) 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)
class BaseDocsTest(unittest.TestCase): def setUp(self): self.root_dir = tempfile.mkdtemp() self.version_dirs = os.path.join(self.root_dir, 'myservice', '2014-01-01') os.makedirs(self.version_dirs) self.model_file = os.path.join(self.version_dirs, 'service-2.json') self.waiter_model_file = os.path.join(self.version_dirs, 'waiters-2.json') self.paginator_model_file = os.path.join(self.version_dirs, 'paginators-1.json') self.resource_model_file = os.path.join(self.version_dirs, 'resources-1.json') self.example_model_file = os.path.join(self.version_dirs, 'examples-1.json') self.json_model = {} self.waiter_json_model = {} self.paginator_json_model = {} self.resource_json_model = {} self._setup_models() self.doc_name = 'MyDoc' self.doc_structure = DocumentStructure(self.doc_name) self.setup_client_and_resource() def tearDown(self): shutil.rmtree(self.root_dir) def setup_client_and_resource(self): self._write_models() self.loader = Loader(extra_search_paths=[self.root_dir]) self.botocore_session = ibm_botocore.session.get_session() self.botocore_session.register_component('data_loader', self.loader) self.session = Session(botocore_session=self.botocore_session, region_name='us-east-1') self.client = self.session.client('myservice', 'us-east-1') self.resource = self.session.resource('myservice', 'us-east-1') def _setup_models(self): self.json_model = { 'metadata': { 'apiVersion': '2014-01-01', 'endpointPrefix': 'myservice', 'signatureVersion': 'v4', 'serviceFullName': 'AWS MyService', 'protocol': 'query', 'serviceId': 'MyService', }, 'operations': { 'SampleOperation': { 'name': 'SampleOperation', 'input': { 'shape': 'SampleOperationInputOutput' }, 'output': { 'shape': 'SampleOperationInputOutput' } } }, 'shapes': { 'SampleOperationInputOutput': { 'type': 'structure', 'members': OrderedDict([ ('Foo', { 'shape': 'String', 'documentation': 'Documents Foo' }), ('Bar', { 'shape': 'String', 'documentation': 'Documents Bar' }), ]) }, 'String': { 'type': 'string' } } } self.example_json_model = { "version": 1, "examples": { "SampleOperation": [{ "id": "sample-id", "title": "sample-title", "description": "Sample Description.", "input": OrderedDict([ ("Foo", "bar"), ]), "comments": { "input": { "Foo": "biz" }, } }] } } self.waiter_json_model = { "version": 2, "waiters": { "SampleOperationComplete": { "delay": 15, "operation": "SampleOperation", "maxAttempts": 40, "acceptors": [{ "expected": "complete", "matcher": "pathAll", "state": "success", "argument": "Biz" }, { "expected": "failed", "matcher": "pathAny", "state": "failure", "argument": "Biz" }] } } } self.paginator_json_model = { "pagination": { "SampleOperation": { "input_token": "NextResult", "output_token": "NextResult", "limit_key": "MaxResults", "result_key": "Biz" } } } self.resource_json_model = { "service": { "actions": OrderedDict([("SampleOperation", { "request": { "operation": "SampleOperation" } }), ("SampleListReturnOperation", { "request": { "operation": "SampleOperation" }, "resource": { "type": "Sample", "identifiers": [{ "target": "Name", "source": "response", "path": "Samples[].Name" }], "path": "Samples[]" } })]), "has": { "Sample": { "resource": { "type": "Sample", "identifiers": [{ "target": "Name", "source": "input" }] } } }, "hasMany": { "Samples": { "request": { "operation": "SampleOperation" }, "resource": { "type": "Sample", "identifiers": [{ "target": "Name", "source": "response", "path": "Samples[].Foo" }] } } } }, "resources": { "Sample": { "identifiers": [{ "name": "Name", "memberName": "Foo" }], "shape": "SampleOperationInputOutput", "load": { "request": { "operation": "SampleOperation", "params": [{ "target": "Foo", "source": "identifier", "name": "Name" }] } }, "actions": { "Operate": { "request": { "operation": "SampleOperation", "params": [{ "target": "Foo", "source": "identifier", "name": "Name" }] } } }, "batchActions": { "Operate": { "request": { "operation": "SampleOperation", "params": [{ "target": "Samples[].Foo", "source": "identifier", "name": "Name" }] } } }, "has": { "RelatedSample": { "resource": { "type": "Sample", "identifiers": [{ "target": "Name", "source": "data", "path": "Foo" }] } } }, "waiters": { "Complete": { "waiterName": "SampleOperationComplete", "params": [{ "target": "Foo", "source": "identifier", "name": "Name" }] } } } } } def _write_models(self): with open(self.resource_model_file, 'w') as f: json.dump(self.resource_json_model, f) with open(self.waiter_model_file, 'w') as f: json.dump(self.waiter_json_model, f) with open(self.paginator_model_file, 'w') as f: json.dump(self.paginator_json_model, f) with open(self.model_file, 'w') as f: json.dump(self.json_model, f) with open(self.example_model_file, 'w') as f: json.dump(self.example_json_model, f) def add_shape(self, shape): shape_name = list(shape.keys())[0] self.json_model['shapes'][shape_name] = shape[shape_name] def add_shape_to_params(self, param_name, shape_name, documentation=None, is_required=False): params_shape = self.json_model['shapes']['SampleOperationInputOutput'] member = {'shape': shape_name} if documentation is not None: member['documentation'] = documentation params_shape['members'][param_name] = member if is_required: required_list = params_shape.get('required', []) required_list.append(param_name) params_shape['required'] = required_list def assert_contains_lines_in_order(self, lines, contents=None): if contents is None: contents = self.doc_structure.flush_structure().decode('utf-8') for line in lines: self.assertIn(line, contents) beginning = contents.find(line) contents = contents[(beginning + len(line)):] def assert_not_contains_lines(self, lines): contents = self.doc_structure.flush_structure().decode('utf-8') for line in lines: self.assertNotIn(line, contents)
class BaseDocsTest(unittest.TestCase): def setUp(self): self.root_dir = tempfile.mkdtemp() self.version_dirs = os.path.join(self.root_dir, 'myservice', '2014-01-01') os.makedirs(self.version_dirs) self.model_file = os.path.join(self.version_dirs, 'service-2.json') self.waiter_model_file = os.path.join(self.version_dirs, 'waiters-2.json') self.paginator_model_file = os.path.join(self.version_dirs, 'paginators-1.json') self.example_model_file = os.path.join(self.version_dirs, 'examples-1.json') self.json_model = {} self.nested_json_model = {} self._setup_models() self.build_models() self.events = HierarchicalEmitter() self.setup_client() self.doc_name = 'MyDoc' self.doc_structure = DocumentStructure(self.doc_name, target='html') def tearDown(self): shutil.rmtree(self.root_dir) def setup_client(self): with open(self.example_model_file, 'w') as f: json.dump(self.example_json_model, f) with open(self.waiter_model_file, 'w') as f: json.dump(self.waiter_json_model, f) with open(self.paginator_model_file, 'w') as f: json.dump(self.paginator_json_model, f) with open(self.model_file, 'w') as f: json.dump(self.json_model, f) self.loader = Loader(extra_search_paths=[self.root_dir]) endpoint_resolver = mock.Mock() endpoint_resolver.construct_endpoint.return_value = { 'hostname': 'foo.us-east-1', 'partition': 'aws', 'endpointName': 'us-east-1', 'signatureVersions': ['v4'] } self.creator = ClientCreator(loader=self.loader, endpoint_resolver=endpoint_resolver, user_agent='user-agent', event_emitter=self.events, retry_handler_factory=mock.Mock(), retry_config_translator=mock.Mock(), exceptions_factory=mock.Mock()) self.client = self.creator.create_client('myservice', 'us-east-1') def _setup_models(self): self.json_model = { 'metadata': { 'apiVersion': '2014-01-01', 'endpointPrefix': 'myservice', 'signatureVersion': 'v4', 'serviceFullName': 'AWS MyService', 'uid': 'myservice-2014-01-01', 'protocol': 'query' }, 'operations': { 'SampleOperation': { 'name': 'SampleOperation', 'input': { 'shape': 'SampleOperationInputOutput' }, 'output': { 'shape': 'SampleOperationInputOutput' } } }, 'shapes': { 'SampleOperationInputOutput': { 'type': 'structure', 'members': OrderedDict() }, 'String': { 'type': 'string' } } } self.waiter_json_model = { "version": 2, "waiters": { "SampleOperationComplete": { "delay": 15, "operation": "SampleOperation", "maxAttempts": 40, "acceptors": [{ "expected": "complete", "matcher": "pathAll", "state": "success", "argument": "Biz" }, { "expected": "failed", "matcher": "pathAny", "state": "failure", "argument": "Biz" }] } } } self.paginator_json_model = { "pagination": { "SampleOperation": { "input_token": "NextResult", "output_token": "NextResult", "limit_key": "MaxResults", "result_key": "Biz" } } } self.example_json_model = { "version": 1, "examples": { "SampleOperation": [{ "id": "sample-id", "title": "sample-title", "description": "Sample Description.", "input": OrderedDict([ ("Biz", "foo"), ]), "comments": { "input": { "Biz": "bar" }, } }] } } def build_models(self): self.service_model = ServiceModel(self.json_model) self.operation_model = OperationModel( self.json_model['operations']['SampleOperation'], self.service_model) def add_shape(self, shape): shape_name = list(shape.keys())[0] self.json_model['shapes'][shape_name] = shape[shape_name] def add_shape_to_params(self, param_name, shape_name, documentation=None, is_required=False): params_shape = self.json_model['shapes']['SampleOperationInputOutput'] member = {'shape': shape_name} if documentation is not None: member['documentation'] = documentation params_shape['members'][param_name] = member if is_required: required_list = params_shape.get('required', []) required_list.append(param_name) params_shape['required'] = required_list def assert_contains_line(self, line): contents = self.doc_structure.flush_structure().decode('utf-8') self.assertIn(line, contents) def assert_contains_lines_in_order(self, lines): contents = self.doc_structure.flush_structure().decode('utf-8') for line in lines: self.assertIn(line, contents) beginning = contents.find(line) contents = contents[(beginning + len(line)):] def assert_not_contains_line(self, line): contents = self.doc_structure.flush_structure().decode('utf-8') self.assertNotIn(line, contents) def assert_not_contains_lines(self, lines): contents = self.doc_structure.flush_structure().decode('utf-8') for line in lines: self.assertNotIn(line, contents)
def document_service(self): """Documents an entire service. :returns: The reStructured text of the documented service. """ doc_structure = DocumentStructure(self._service_name, section_names=self.sections, target='html') self.title(doc_structure.get_section('title')) self.table_of_contents(doc_structure.get_section('table-of-contents')) self.client_api(doc_structure.get_section('client')) self.paginator_api(doc_structure.get_section('paginators')) self.waiter_api(doc_structure.get_section('waiters')) if self._service_resource: self._document_service_resource( doc_structure.get_section('service-resource')) self._document_resources(doc_structure.get_section('resources')) self._document_examples(doc_structure.get_section('examples')) return doc_structure.flush_structure()
def setUp(self): self.name = 'mydoc' self.doc_structure = DocumentStructure(self.name)
class TestDocumentStructure(unittest.TestCase): def setUp(self): self.name = 'mydoc' self.doc_structure = DocumentStructure(self.name) def test_name(self): self.assertEqual(self.doc_structure.name, self.name) def test_path(self): self.assertEqual(self.doc_structure.path, [self.name]) self.doc_structure.path = ['foo'] self.assertEqual(self.doc_structure.path, ['foo']) def test_add_new_section(self): section = self.doc_structure.add_new_section('mysection') # Ensure the name of the section is correct self.assertEqual(section.name, 'mysection') # Ensure we can get the section. self.assertEqual(self.doc_structure.get_section('mysection'), section) # Ensure the path is correct self.assertEqual(section.path, ['mydoc', 'mysection']) # Ensure some of the necessary attributes are passed to the # the section. self.assertEqual(section.style.indentation, self.doc_structure.style.indentation) self.assertEqual(section.translation_map, self.doc_structure.translation_map) self.assertEqual(section.hrefs, self.doc_structure.hrefs) def test_delete_section(self): section = self.doc_structure.add_new_section('mysection') self.assertEqual(self.doc_structure.get_section('mysection'), section) self.doc_structure.delete_section('mysection') with self.assertRaises(KeyError): section.get_section('mysection') def test_create_sections_at_instantiation(self): sections = ['intro', 'middle', 'end'] self.doc_structure = DocumentStructure(self.name, section_names=sections) # Ensure the sections are attached to the new document structure. for section_name in sections: section = self.doc_structure.get_section(section_name) self.assertEqual(section.name, section_name) def test_flush_structure(self): section = self.doc_structure.add_new_section('mysection') subsection = section.add_new_section('mysubsection') self.doc_structure.writeln('1') section.writeln('2') subsection.writeln('3') second_section = self.doc_structure.add_new_section('mysection2') second_section.writeln('4') contents = self.doc_structure.flush_structure() # Ensure the contents were flushed out correctly self.assertEqual(contents, six.b('1\n2\n3\n4\n')) def test_flush_structure_hrefs(self): section = self.doc_structure.add_new_section('mysection') section.writeln('section contents') self.doc_structure.hrefs['foo'] = 'www.foo.com' section.hrefs['bar'] = 'www.bar.com' contents = self.doc_structure.flush_structure() self.assertIn(six.b('.. _foo: www.foo.com'), contents) self.assertIn(six.b('.. _bar: www.bar.com'), contents) def test_available_sections(self): self.doc_structure.add_new_section('mysection') self.doc_structure.add_new_section('mysection2') self.assertEqual(self.doc_structure.available_sections, ['mysection', 'mysection2']) def test_context(self): context = {'Foo': 'Bar'} section = self.doc_structure.add_new_section('mysection', context=context) self.assertEqual(section.context, context) # Make sure if context is not specified it is empty. section = self.doc_structure.add_new_section('mysection2') self.assertEqual(section.context, {}) def test_remove_all_sections(self): self.doc_structure.add_new_section('mysection2') self.doc_structure.remove_all_sections() self.assertEqual(self.doc_structure.available_sections, []) def test_clear_text(self): self.doc_structure.write('Foo') self.doc_structure.clear_text() self.assertEqual(self.doc_structure.flush_structure(), six.b(''))