Updated signatures to support sphinx domain (#3615)

Updated signatures to support sphinx domain

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,

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(

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}'

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.'
     )

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: <root>/reference/services/<service>/<resource_name>/<reference_name>.rst

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

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,

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={',

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=[',

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'),
         )

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

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',

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(',

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 '