From 12dddb1284510c6baa0766f41939b8c9138aacd3 Mon Sep 17 00:00:00 2001 From: jonathan343 <43360731+jonathan343@users.noreply.github.com> Date: Thu, 16 Mar 2023 10:26:27 -0700 Subject: [PATCH] Updated signatures to support sphinx domain (#3615) Updated signatures to support sphinx domain --- boto3/docs/action.py | 13 ++++++++++--- boto3/docs/attr.py | 18 ++++++++++++++---- boto3/docs/base.py | 7 +++++++ boto3/docs/collection.py | 12 +++++++++--- boto3/docs/resource.py | 16 ++++++++++++---- boto3/docs/subresource.py | 8 ++++++-- boto3/docs/waiter.py | 10 ++++++++-- tests/functional/docs/test_dynamodb.py | 4 ++-- tests/functional/docs/test_ec2.py | 2 +- tests/functional/docs/test_s3.py | 4 ++-- tests/functional/docs/test_smoke.py | 2 +- tests/unit/docs/test_action.py | 10 +++++----- tests/unit/docs/test_client.py | 8 ++++---- tests/unit/docs/test_collection.py | 2 +- tests/unit/docs/test_resource.py | 14 +++++++------- tests/unit/docs/test_service.py | 18 +++++++++--------- tests/unit/docs/test_subresource.py | 2 +- tests/unit/docs/test_waiter.py | 2 +- 18 files changed, 100 insertions(+), 52 deletions(-) diff --git a/boto3/docs/action.py b/boto3/docs/action.py index acfcebf1b3..a6e76d474a 100644 --- a/boto3/docs/action.py +++ b/boto3/docs/action.py @@ -55,7 +55,10 @@ def document_actions(self, section): # Create a new DocumentStructure for each action and add contents. action_doc = DocumentStructure(action_name, target='html') action_doc.add_title_section(action_name) - action_section = action_doc.add_new_section(action_name) + action_section = action_doc.add_new_section( + action_name, + context={'qualifier': f'{self.class_name}.'}, + ) if action_name in ['load', 'reload'] and self._resource_model.load: document_load_reload_action( section=action_section, @@ -124,9 +127,12 @@ def document_action( example_prefix = '{} = {}.{}'.format( example_return_value, example_resource_name, action_model.name ) + full_action_name = ( + f"{section.context.get('qualifier', '')}{action_model.name}" + ) document_model_driven_resource_method( section=section, - method_name=action_model.name, + method_name=full_action_name, operation_model=operation_model, event_emitter=event_emitter, method_description=operation_model.documentation, @@ -176,9 +182,10 @@ def document_load_reload_action( if service_model.service_name == resource_name: example_resource_name = resource_name example_prefix = f'{example_resource_name}.{action_name}' + full_action_name = f"{section.context.get('qualifier', '')}{action_name}" document_model_driven_method( section=section, - method_name=action_name, + method_name=full_action_name, operation_model=OperationModel({}, service_model), event_emitter=event_emitter, method_description=description, diff --git a/boto3/docs/attr.py b/boto3/docs/attr.py index ced8bc287a..a968da2901 100644 --- a/boto3/docs/attr.py +++ b/boto3/docs/attr.py @@ -29,7 +29,8 @@ def document_attribute( include_signature=True, ): if include_signature: - section.style.start_sphinx_py_attr(attr_name) + full_attr_name = f"{section.context.get('qualifier', '')}{attr_name}" + section.style.start_sphinx_py_attr(full_attr_name) # Note that an attribute may have one, may have many, or may have no # operations that back the resource's shape. So we just set the # operation_name to the resource name if we ever to hook in and modify @@ -42,10 +43,16 @@ def document_attribute( def document_identifier( - section, resource_name, identifier_model, include_signature=True + section, + resource_name, + identifier_model, + include_signature=True, ): if include_signature: - section.style.start_sphinx_py_attr(identifier_model.name) + full_identifier_name = ( + f"{section.context.get('qualifier', '')}{identifier_model.name}" + ) + section.style.start_sphinx_py_attr(full_identifier_name) description = get_identifier_description( resource_name, identifier_model.name ) @@ -54,7 +61,10 @@ def document_identifier( def document_reference(section, reference_model, include_signature=True): if include_signature: - section.style.start_sphinx_py_attr(reference_model.name) + full_reference_name = ( + f"{section.context.get('qualifier', '')}{reference_model.name}" + ) + section.style.start_sphinx_py_attr(full_reference_name) reference_type = f'(:py:class:`{reference_model.resource.type}`) ' section.write(reference_type) section.include_doc_string( diff --git a/boto3/docs/base.py b/boto3/docs/base.py index 7945d0757d..6e072fb9fb 100644 --- a/boto3/docs/base.py +++ b/boto3/docs/base.py @@ -39,3 +39,10 @@ def __init__(self, resource, root_docs_path): self._resource_sub_path = self._resource_name.lower() if self._resource_name == self._service_name: self._resource_sub_path = 'service-resource' + + @property + def class_name(self): + resource_class_name = self._resource_name + if self._resource_name == self._service_name: + resource_class_name = 'ServiceResource' + return f'{self._service_docs_name}.{resource_class_name}' diff --git a/boto3/docs/collection.py b/boto3/docs/collection.py index 9de772cc6f..bedc5006e8 100644 --- a/boto3/docs/collection.py +++ b/boto3/docs/collection.py @@ -45,7 +45,8 @@ def document_collections(self, section): collection_doc = DocumentStructure(collection.name, target='html') collection_doc.add_title_section(collection.name) collection_section = collection_doc.add_new_section( - collection.name + collection.name, + context={'qualifier': f'{self.class_name}.'}, ) self._document_collection(collection_section, collection) @@ -90,7 +91,9 @@ def _document_collection(self, section, collection): def document_collection_object( - section, collection_model, include_signature=True + section, + collection_model, + include_signature=True, ): """Documents a collection resource object @@ -102,7 +105,10 @@ def document_collection_object( It is useful for generating docstrings. """ if include_signature: - section.style.start_sphinx_py_attr(collection_model.name) + full_collection_name = ( + f"{section.context.get('qualifier', '')}{collection_model.name}" + ) + section.style.start_sphinx_py_attr(full_collection_name) section.include_doc_string( f'A collection of {collection_model.resource.type} resources.' ) diff --git a/boto3/docs/resource.py b/boto3/docs/resource.py index b4eef3c544..e669c6e6b1 100644 --- a/boto3/docs/resource.py +++ b/boto3/docs/resource.py @@ -159,7 +159,8 @@ def _add_identifiers(self, section): identifier_doc = DocumentStructure(identifier.name, target='html') identifier_doc.add_title_section(identifier.name) identifier_section = identifier_doc.add_new_section( - identifier.name + identifier.name, + context={'qualifier': f'{self.class_name}.'}, ) document_identifier( section=identifier_section, @@ -209,7 +210,10 @@ def _add_attributes(self, section): # Create a new DocumentStructure for each attribute and add contents. attribute_doc = DocumentStructure(attr_name, target='html') attribute_doc.add_title_section(attr_name) - attribute_section = attribute_doc.add_new_section(attr_name) + attribute_section = attribute_doc.add_new_section( + attr_name, + context={'qualifier': f'{self.class_name}.'}, + ) document_attribute( section=attribute_section, service_name=self._service_name, @@ -250,9 +254,13 @@ def _add_references(self, section): # Create a new DocumentStructure for each reference and add contents. reference_doc = DocumentStructure(reference.name, target='html') reference_doc.add_title_section(reference.name) - reference_section = reference_doc.add_new_section(reference.name) + reference_section = reference_doc.add_new_section( + reference.name, + context={'qualifier': f'{self.class_name}.'}, + ) document_reference( - section=reference_section, reference_model=reference + section=reference_section, + reference_model=reference, ) # Write references in individual/nested files. # Path: /reference/services///.rst diff --git a/boto3/docs/subresource.py b/boto3/docs/subresource.py index b0c4ff4a69..d4af78cf5e 100644 --- a/boto3/docs/subresource.py +++ b/boto3/docs/subresource.py @@ -51,7 +51,8 @@ def document_sub_resources(self, section): ) sub_resource_doc.add_title_section(sub_resource.name) sub_resource_section = sub_resource_doc.add_new_section( - sub_resource.name + sub_resource.name, + context={'qualifier': f'{self.class_name}.'}, ) document_sub_resource( section=sub_resource_section, @@ -99,8 +100,11 @@ def document_sub_resource( if include_signature: signature_args = get_identifier_args_for_signature(identifiers_needed) + full_sub_resource_name = ( + f"{section.context.get('qualifier', '')}{sub_resource_model.name}" + ) section.style.start_sphinx_py_method( - sub_resource_model.name, signature_args + full_sub_resource_name, signature_args ) method_intro_section = section.add_new_section('method-intro') diff --git a/boto3/docs/waiter.py b/boto3/docs/waiter.py index 559447cab5..8aa1348a77 100644 --- a/boto3/docs/waiter.py +++ b/boto3/docs/waiter.py @@ -47,7 +47,10 @@ def document_resource_waiters(self, section): # Create a new DocumentStructure for each waiter and add contents. waiter_doc = DocumentStructure(waiter.name, target='html') waiter_doc.add_title_section(waiter.name) - waiter_section = waiter_doc.add_new_section(waiter.name) + waiter_section = waiter_doc.add_new_section( + waiter.name, + context={'qualifier': f'{self.class_name}.'}, + ) document_resource_waiter( section=waiter_section, resource_name=self._resource_name, @@ -101,9 +104,12 @@ def document_resource_waiter( example_prefix = '{}.{}'.format( xform_name(resource_name), resource_waiter_model.name ) + full_waiter_name = ( + f"{section.context.get('qualifier', '')}{resource_waiter_model.name}" + ) document_model_driven_method( section=section, - method_name=resource_waiter_model.name, + method_name=full_waiter_name, operation_model=operation_model, event_emitter=event_emitter, example_prefix=example_prefix, diff --git a/tests/functional/docs/test_dynamodb.py b/tests/functional/docs/test_dynamodb.py index fb5e41f6cb..af18317b66 100644 --- a/tests/functional/docs/test_dynamodb.py +++ b/tests/functional/docs/test_dynamodb.py @@ -47,7 +47,7 @@ def test_batch_writer_is_documented(self): self.assert_contains_lines_in_order( [ '************\nbatch_writer\n************', - '.. py:method:: batch_writer(overwrite_by_pkeys=None)', + '.. py:method:: DynamoDB.Table.batch_writer(overwrite_by_pkeys=None)', ], self.get_nested_file_contents('dynamodb', 'table', 'batch_writer'), ) @@ -61,7 +61,7 @@ def test_document_interface_is_documented(self): '********', 'put_item', '********', - '.. py:method:: put_item(**kwargs)', + '.. py:method:: DynamoDB.Table.put_item(**kwargs)', # Make sure the request syntax is as expected. 'response = table.put_item(', 'Item={', diff --git a/tests/functional/docs/test_ec2.py b/tests/functional/docs/test_ec2.py index cd01723b78..aef6fb03af 100644 --- a/tests/functional/docs/test_ec2.py +++ b/tests/functional/docs/test_ec2.py @@ -47,7 +47,7 @@ def test_delete_tags_method_is_documented(self): self.assert_contains_lines_in_order( [ 'delete_tags', - '.. py:method:: delete_tags(**kwargs)', + '.. py:method:: EC2.Instance.delete_tags(**kwargs)', 'response = instance.delete_tags(', 'DryRun=True|False,', 'Tags=[', diff --git a/tests/functional/docs/test_s3.py b/tests/functional/docs/test_s3.py index b53b7ec382..1f2bf0e307 100644 --- a/tests/functional/docs/test_s3.py +++ b/tests/functional/docs/test_s3.py @@ -48,14 +48,14 @@ def test_file_transfer_methods_are_documented(self): self.assert_contains_lines_in_order( [ 'download_file', - '.. py:method:: download_file(', + '.. py:method:: S3.Client.download_file(', ], self.get_nested_file_contents('s3', 'client', 'download_file'), ) self.assert_contains_lines_in_order( [ 'upload_file', - '.. py:method:: upload_file(', + '.. py:method:: S3.Client.upload_file(', ], self.get_nested_file_contents('s3', 'client', 'upload_file'), ) diff --git a/tests/functional/docs/test_smoke.py b/tests/functional/docs/test_smoke.py index a1b3e10544..b672b1722c 100644 --- a/tests/functional/docs/test_smoke.py +++ b/tests/functional/docs/test_smoke.py @@ -133,7 +133,7 @@ def _assert_has_client_documentation(generated_docs, service_name, client): _assert_contains_lines_in_order( [ f'{method_name}', - f'.. py:method:: {method_name}(', + f'.. py:method:: {client.__class__.__name__}.Client.{method_name}(', ], get_nested_file_contents(service_name, 'client', method_name), ) diff --git a/tests/unit/docs/test_action.py b/tests/unit/docs/test_action.py index 9543985af7..f2092d3bea 100644 --- a/tests/unit/docs/test_action.py +++ b/tests/unit/docs/test_action.py @@ -32,7 +32,7 @@ def test_document_service_resource_actions(self): self.assert_contains_lines_in_order( [ 'sample_operation', - '.. py:method:: sample_operation(**kwargs)', + '.. py:method:: MyService.ServiceResource.sample_operation(**kwargs)', ' **Request Syntax**', ' ::', ' response = myservice.sample_operation(', @@ -79,7 +79,7 @@ def test_document_nonservice_resource_actions(self): self.assert_contains_lines_in_order( [ 'load', - '.. py:method:: load()', + '.. py:method:: MyService.Sample.load()', ( ' Calls :py:meth:`MyService.Client.sample_operation` to update ' 'the attributes of the Sample resource' @@ -94,7 +94,7 @@ def test_document_nonservice_resource_actions(self): self.assert_contains_lines_in_order( [ 'operate', - '.. py:method:: operate(**kwargs)', + '.. py:method:: MyService.Sample.operate(**kwargs)', ' **Request Syntax** ', ' ::', ' response = sample.operate(', @@ -121,7 +121,7 @@ def test_document_nonservice_resource_actions(self): self.assert_contains_lines_in_order( [ 'reload', - '.. py:method:: reload()', + '.. py:method:: MyService.Sample.reload()', ( ' Calls :py:meth:`MyService.Client.sample_operation` to update ' 'the attributes of the Sample resource' @@ -136,7 +136,7 @@ def test_document_nonservice_resource_actions(self): self.assert_contains_lines_in_order( [ 'get_available_subresources', - '.. py:method:: get_available_subresources()', + '.. py:method:: MyService.Sample.get_available_subresources()', 'Returns a list of all the available sub-resources for this', ':returns: A list containing the name of each sub-resource for this', ':rtype: list of str', diff --git a/tests/unit/docs/test_client.py b/tests/unit/docs/test_client.py index 58fe853793..11a42fa3cf 100644 --- a/tests/unit/docs/test_client.py +++ b/tests/unit/docs/test_client.py @@ -46,7 +46,7 @@ def test_document_client(self): self.assert_contains_lines_in_order( [ 'can_paginate', - '.. py:method:: can_paginate(operation_name)', + '.. py:method:: MyService.Client.can_paginate(operation_name)', ], self.get_nested_service_contents( 'myservice', 'client', 'can_paginate' @@ -55,7 +55,7 @@ def test_document_client(self): self.assert_contains_lines_in_order( [ 'get_paginator', - '.. py:method:: get_paginator(operation_name)', + '.. py:method:: MyService.Client.get_paginator(operation_name)', ], self.get_nested_service_contents( 'myservice', 'client', 'get_paginator' @@ -64,7 +64,7 @@ def test_document_client(self): self.assert_contains_lines_in_order( [ 'get_waiter', - '.. py:method:: get_waiter(waiter_name)', + '.. py:method:: MyService.Client.get_waiter(waiter_name)', ], self.get_nested_service_contents( 'myservice', 'client', 'get_waiter' @@ -73,7 +73,7 @@ def test_document_client(self): self.assert_contains_lines_in_order( [ 'sample_operation', - '.. py:method:: sample_operation(**kwargs)', + '.. py:method:: MyService.Client.sample_operation(**kwargs)', ' **Request Syntax**', ' ::', ' response = client.sample_operation(', diff --git a/tests/unit/docs/test_collection.py b/tests/unit/docs/test_collection.py index 430a475a44..0b9d6b167e 100644 --- a/tests/unit/docs/test_collection.py +++ b/tests/unit/docs/test_collection.py @@ -31,7 +31,7 @@ def test_document_collections(self): self.assert_contains_lines_in_order( [ 'samples', - '.. py:attribute:: samples', + '.. py:attribute:: MyService.ServiceResource.samples', ' A collection of Sample resources.' 'A Sample Collection will include all resources by default, ' 'and extreme caution should be taken when performing actions ' diff --git a/tests/unit/docs/test_resource.py b/tests/unit/docs/test_resource.py index 3df974e95e..4d7f3ad2ef 100644 --- a/tests/unit/docs/test_resource.py +++ b/tests/unit/docs/test_resource.py @@ -66,14 +66,14 @@ def test_document_resource(self): self.assert_contains_lines_in_order( [ 'name', - '.. py:attribute:: name', + '.. py:attribute:: MyService.Sample.name', ], self.get_nested_service_contents('myservice', 'sample', 'name'), ) self.assert_contains_lines_in_order( [ 'bar', - '.. py:attribute:: bar', + '.. py:attribute:: MyService.Sample.bar', ' - *(string) --* Documents Bar', ], self.get_nested_service_contents('myservice', 'sample', 'bar'), @@ -81,14 +81,14 @@ def test_document_resource(self): self.assert_contains_lines_in_order( [ 'load', - '.. py:method:: load()', + '.. py:method:: MyService.Sample.load()', ], self.get_nested_service_contents('myservice', 'sample', 'load'), ) self.assert_contains_lines_in_order( [ 'wait_until_complete', - '.. py:method:: wait_until_complete(**kwargs)', + '.. py:method:: MyService.Sample.wait_until_complete(**kwargs)', ], self.get_nested_service_contents( 'myservice', 'sample', 'wait_until_complete' @@ -137,7 +137,7 @@ def test_document_resource(self): self.assert_contains_lines_in_order( [ 'sample_operation', - '.. py:method:: sample_operation(**kwargs)', + '.. py:method:: MyService.ServiceResource.sample_operation(**kwargs)', ], self.get_nested_service_contents( 'myservice', 'service-resource', 'sample_operation' @@ -146,7 +146,7 @@ def test_document_resource(self): self.assert_contains_lines_in_order( [ 'Sample', - '.. py:method:: Sample(name)', + '.. py:method:: MyService.ServiceResource.Sample(name)', ], self.get_nested_service_contents( 'myservice', 'service-resource', 'Sample' @@ -155,7 +155,7 @@ def test_document_resource(self): self.assert_contains_lines_in_order( [ 'samples', - '.. py:attribute:: samples', + '.. py:attribute:: MyService.ServiceResource.samples', ' .. py:method:: all()', ' .. py:method:: filter(**kwargs)', ' .. py:method:: limit(**kwargs)', diff --git a/tests/unit/docs/test_service.py b/tests/unit/docs/test_service.py index d67904b439..a7f97eb2d8 100644 --- a/tests/unit/docs/test_service.py +++ b/tests/unit/docs/test_service.py @@ -125,7 +125,7 @@ def test_document_service(self): self.assert_contains_lines_in_order( [ 'sample_operation', - '.. py:method:: sample_operation(**kwargs)', + '.. py:method:: MyService.Client.sample_operation(**kwargs)', ' **Examples** ', ' Sample Description.', ' ::', @@ -158,7 +158,7 @@ def test_document_service(self): self.assert_contains_lines_in_order( [ 'sample_operation', - '.. py:method:: sample_operation(**kwargs)', + '.. py:method:: MyService.ServiceResource.sample_operation(**kwargs)', ], self.get_nested_service_contents( 'myservice', 'service-resource', 'sample_operation' @@ -167,7 +167,7 @@ def test_document_service(self): self.assert_contains_lines_in_order( [ 'Sample', - '.. py:method:: Sample(name)', + '.. py:method:: MyService.ServiceResource.Sample(name)', ], self.get_nested_service_contents( 'myservice', 'service-resource', 'Sample' @@ -176,7 +176,7 @@ def test_document_service(self): self.assert_contains_lines_in_order( [ 'samples', - '.. py:attribute:: samples', + '.. py:attribute:: MyService.ServiceResource.samples', ' .. py:method:: all()', ' .. py:method:: filter(**kwargs)', ' .. py:method:: limit(**kwargs)', @@ -189,35 +189,35 @@ def test_document_service(self): self.assert_contains_lines_in_order( [ 'name', - '.. py:attribute:: name', + '.. py:attribute:: MyService.Sample.name', ], self.get_nested_service_contents('myservice', 'sample', 'name'), ) self.assert_contains_lines_in_order( [ 'name', - '.. py:attribute:: name', + '.. py:attribute:: MyService.Sample.name', ], self.get_nested_service_contents('myservice', 'sample', 'name'), ) self.assert_contains_lines_in_order( [ 'bar', - '.. py:attribute:: bar', + '.. py:attribute:: MyService.Sample.bar', ], self.get_nested_service_contents('myservice', 'sample', 'bar'), ) self.assert_contains_lines_in_order( [ 'load', - '.. py:method:: load()', + '.. py:method:: MyService.Sample.load()', ], self.get_nested_service_contents('myservice', 'sample', 'load'), ) self.assert_contains_lines_in_order( [ 'wait_until_complete', - '.. py:method:: wait_until_complete(**kwargs)', + '.. py:method:: MyService.Sample.wait_until_complete(**kwargs)', ], self.get_nested_service_contents( 'myservice', 'sample', 'wait_until_complete' diff --git a/tests/unit/docs/test_subresource.py b/tests/unit/docs/test_subresource.py index 4e31cd538e..d5058fbde9 100644 --- a/tests/unit/docs/test_subresource.py +++ b/tests/unit/docs/test_subresource.py @@ -32,7 +32,7 @@ def test_document_sub_resources(self): self.assert_contains_lines_in_order( [ 'Sample', - '.. py:method:: Sample(name)', + '.. py:method:: MyService.ServiceResource.Sample(name)', ' Creates a Sample resource.::', " sample = myservice.Sample('name')", ' :type name: string', diff --git a/tests/unit/docs/test_waiter.py b/tests/unit/docs/test_waiter.py index 9a4ff48825..f59991b103 100644 --- a/tests/unit/docs/test_waiter.py +++ b/tests/unit/docs/test_waiter.py @@ -35,7 +35,7 @@ def test_document_resource_waiters(self): self.assert_contains_lines_in_order( [ 'wait_until_complete', - '.. py:method:: wait_until_complete(**kwargs)', + '.. py:method:: MyService.Sample.wait_until_complete(**kwargs)', ( ' Waits until this Sample is complete. This method calls ' ':py:meth:`MyService.Waiter.sample_operation_complete.wait` '