From 102a74b9147faada66ab3924d72da69889254785 Mon Sep 17 00:00:00 2001
From: jonathan343 <43360731+jonathan343@users.noreply.github.com>
Date: Tue, 28 Feb 2023 07:46:27 -0800
Subject: [PATCH] Implemented Nested Docs. (#3597)

* Implemented Nested Docs.

* Manually included js/custom.js since Sphinx < 1.8 doesnt support custom js.

* Added a new Resource section; Improved redirecting from old links.

* Updated Resources notes & redirects; Updated copyright year.
---
 boto3/docs/__init__.py                 |   4 +-
 boto3/docs/action.py                   |  20 +-
 boto3/docs/base.py                     |   9 +
 boto3/docs/collection.py               |  23 ++-
 boto3/docs/resource.py                 | 125 +++++++++---
 boto3/docs/service.py                  |  80 ++++++--
 boto3/docs/subresource.py              |  27 ++-
 boto3/docs/utils.py                    |   5 +-
 boto3/docs/waiter.py                   |  24 ++-
 docs/source/_static/js/custom.js       |  73 +++++++
 docs/source/_templates/layout.html     |   1 +
 docs/source/conf.py                    |   4 +-
 tests/functional/docs/__init__.py      |  23 +++
 tests/functional/docs/test_dynamodb.py | 118 +++++-------
 tests/functional/docs/test_ec2.py      |  28 ++-
 tests/functional/docs/test_s3.py       |  35 +++-
 tests/functional/docs/test_smoke.py    | 116 +++++++----
 tests/unit/docs/__init__.py            |  14 +-
 tests/unit/docs/test_action.py         |  60 +++++-
 tests/unit/docs/test_client.py         | 101 ++++++----
 tests/unit/docs/test_collection.py     |  18 +-
 tests/unit/docs/test_resource.py       | 164 +++++++++++-----
 tests/unit/docs/test_service.py        | 254 +++++++++++++++++++------
 tests/unit/docs/test_subresource.py    |  19 +-
 tests/unit/docs/test_waiter.py         |  16 +-
 25 files changed, 1032 insertions(+), 329 deletions(-)
 create mode 100644 docs/source/_static/js/custom.js

diff --git a/boto3/docs/__init__.py b/boto3/docs/__init__.py
index d1cd8b52f4..261747b42f 100644
--- a/boto3/docs/__init__.py
+++ b/boto3/docs/__init__.py
@@ -32,7 +32,9 @@ def generate_docs(root_dir, session):
         os.makedirs(services_doc_path)
 
     for service_name in session.get_available_services():
-        docs = ServiceDocumenter(service_name, session).document_service()
+        docs = ServiceDocumenter(
+            service_name, session, services_doc_path
+        ).document_service()
         service_doc_path = os.path.join(
             services_doc_path, service_name + '.rst'
         )
diff --git a/boto3/docs/action.py b/boto3/docs/action.py
index 907f428663..acfcebf1b3 100644
--- a/boto3/docs/action.py
+++ b/boto3/docs/action.py
@@ -10,7 +10,10 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+
 from botocore import xform_name
+from botocore.docs.bcdoc.restdoc import DocumentStructure
 from botocore.docs.method import (
     document_custom_method,
     document_model_driven_method,
@@ -18,7 +21,7 @@
 from botocore.model import OperationModel
 from botocore.utils import get_service_module_name
 
-from boto3.docs.base import BaseDocumenter
+from boto3.docs.base import NestedDocumenter
 from boto3.docs.method import document_model_driven_resource_method
 from boto3.docs.utils import (
     add_resource_type_overview,
@@ -27,7 +30,7 @@
 )
 
 
-class ActionDocumenter(BaseDocumenter):
+class ActionDocumenter(NestedDocumenter):
     def document_actions(self, section):
         modeled_actions_list = self._resource_model.actions
         modeled_actions = {}
@@ -49,7 +52,10 @@ def document_actions(self, section):
         )
 
         for action_name in sorted(resource_actions):
-            action_section = section.add_new_section(action_name)
+            # 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)
             if action_name in ['load', 'reload'] and self._resource_model.load:
                 document_load_reload_action(
                     section=action_section,
@@ -71,6 +77,14 @@ def document_actions(self, section):
                 document_custom_method(
                     action_section, action_name, resource_actions[action_name]
                 )
+            # Write actions in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<action_name>.rst
+            actions_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            action_doc.write_to_file(actions_dir_path, action_name)
 
 
 def document_action(
diff --git a/boto3/docs/base.py b/boto3/docs/base.py
index a12d94543f..7945d0757d 100644
--- a/boto3/docs/base.py
+++ b/boto3/docs/base.py
@@ -30,3 +30,12 @@ def __init__(self, resource):
     @property
     def class_name(self):
         return f'{self._service_docs_name}.{self._resource_name}'
+
+
+class NestedDocumenter(BaseDocumenter):
+    def __init__(self, resource, root_docs_path):
+        super().__init__(resource)
+        self._root_docs_path = root_docs_path
+        self._resource_sub_path = self._resource_name.lower()
+        if self._resource_name == self._service_name:
+            self._resource_sub_path = 'service-resource'
diff --git a/boto3/docs/collection.py b/boto3/docs/collection.py
index a1f9ca7faa..9de772cc6f 100644
--- a/boto3/docs/collection.py
+++ b/boto3/docs/collection.py
@@ -10,11 +10,14 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+
 from botocore import xform_name
+from botocore.docs.bcdoc.restdoc import DocumentStructure
 from botocore.docs.method import get_instance_public_methods
 from botocore.docs.utils import DocumentedShape
 
-from boto3.docs.base import BaseDocumenter
+from boto3.docs.base import NestedDocumenter
 from boto3.docs.method import document_model_driven_resource_method
 from boto3.docs.utils import (
     add_resource_type_overview,
@@ -22,7 +25,7 @@
 )
 
 
-class CollectionDocumenter(BaseDocumenter):
+class CollectionDocumenter(NestedDocumenter):
     def document_collections(self, section):
         collections = self._resource.meta.resource_model.collections
         collections_list = []
@@ -37,10 +40,24 @@ def document_collections(self, section):
         )
         self.member_map['collections'] = collections_list
         for collection in collections:
-            collection_section = section.add_new_section(collection.name)
             collections_list.append(collection.name)
+            # Create a new DocumentStructure for each collection and add contents.
+            collection_doc = DocumentStructure(collection.name, target='html')
+            collection_doc.add_title_section(collection.name)
+            collection_section = collection_doc.add_new_section(
+                collection.name
+            )
             self._document_collection(collection_section, collection)
 
+            # Write collections in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<collection_name>.rst
+            collections_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            collection_doc.write_to_file(collections_dir_path, collection.name)
+
     def _document_collection(self, section, collection):
         methods = get_instance_public_methods(
             getattr(self._resource, collection.name)
diff --git a/boto3/docs/resource.py b/boto3/docs/resource.py
index 7d5516e9c1..b4eef3c544 100644
--- a/boto3/docs/resource.py
+++ b/boto3/docs/resource.py
@@ -10,7 +10,10 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+
 from botocore import xform_name
+from botocore.docs.bcdoc.restdoc import DocumentStructure
 from botocore.docs.utils import get_official_service_name
 
 from boto3.docs.action import ActionDocumenter
@@ -32,14 +35,18 @@
 
 
 class ResourceDocumenter(BaseDocumenter):
-    def __init__(self, resource, botocore_session):
+    def __init__(self, resource, botocore_session, root_docs_path):
         super().__init__(resource)
         self._botocore_session = botocore_session
+        self._root_docs_path = root_docs_path
+        self._resource_sub_path = self._resource_name.lower()
+        if self._resource_name == self._service_name:
+            self._resource_sub_path = 'service-resource'
 
     def document_resource(self, section):
         self._add_title(section)
+        self._add_resource_note(section)
         self._add_intro(section)
-        overview_section = section.add_new_section('member-overview')
         self._add_identifiers(section)
         self._add_attributes(section)
         self._add_references(section)
@@ -47,7 +54,6 @@ def document_resource(self, section):
         self._add_sub_resources(section)
         self._add_collections(section)
         self._add_waiters(section)
-        self._add_overview_of_members(overview_section)
 
     def _add_title(self, section):
         section.style.h2(self._resource_name)
@@ -60,23 +66,27 @@ def _add_intro(self, section):
 
         # Write out the class signature.
         class_args = get_identifier_args_for_signature(identifier_names)
-        section.style.start_sphinx_py_class(
+        start_class = section.add_new_section('start_class')
+        start_class.style.start_sphinx_py_class(
             class_name=f'{self.class_name}({class_args})'
         )
 
         # Add as short description about the resource
-        description_section = section.add_new_section('description')
+        description_section = start_class.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')
+        example_section = start_class.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')
+        param_section = start_class.add_new_section('params')
         self._add_params_description(param_section, identifier_names)
 
+        end_class = section.add_new_section('end_class')
+        end_class.style.end_sphinx_py_class()
+
     def _add_description(self, section):
         official_service_name = get_official_service_name(self._service_model)
         section.write(
@@ -118,23 +128,15 @@ def _add_params_description(self, section, identifier_names):
             section.write(f':param {identifier_name}: {description}')
             section.style.new_line()
 
-    def _add_overview_of_members(self, section):
-        for resource_member_type in self.member_map:
-            section.style.new_line()
-            section.write(
-                f'These are the resource\'s available {resource_member_type}:'
-            )
-            section.style.new_line()
-            for member in self.member_map[resource_member_type]:
-                if resource_member_type in (
-                    'attributes',
-                    'collections',
-                    'identifiers',
-                    'references',
-                ):
-                    section.style.li(f':py:attr:`{member}`')
-                else:
-                    section.style.li(f':py:meth:`{member}()`')
+    def _add_overview_of_member_type(self, section, resource_member_type):
+        section.style.new_line()
+        section.write(
+            f'These are the resource\'s available {resource_member_type}:'
+        )
+        section.style.new_line()
+        section.style.toctree()
+        for member in self.member_map[resource_member_type]:
+            section.style.tocitem(f'{member}')
 
     def _add_identifiers(self, section):
         identifiers = self._resource.meta.resource_model.identifiers
@@ -152,13 +154,29 @@ def _add_identifiers(self, section):
                 intro_link='identifiers_attributes_intro',
             )
         for identifier in identifiers:
-            identifier_section = section.add_new_section(identifier.name)
             member_list.append(identifier.name)
+            # Create a new DocumentStructure for each identifier and add contents.
+            identifier_doc = DocumentStructure(identifier.name, target='html')
+            identifier_doc.add_title_section(identifier.name)
+            identifier_section = identifier_doc.add_new_section(
+                identifier.name
+            )
             document_identifier(
                 section=identifier_section,
                 resource_name=self._resource_name,
                 identifier_model=identifier,
             )
+            # Write identifiers in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<identifier_name>.rst
+            identifiers_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            identifier_doc.write_to_file(identifiers_dir_path, identifier.name)
+
+        if identifiers:
+            self._add_overview_of_member_type(section, 'identifiers')
 
     def _add_attributes(self, section):
         service_model = self._resource.meta.client.meta.service_model
@@ -187,8 +205,11 @@ def _add_attributes(self, section):
             self.member_map['attributes'] = attribute_list
         for attr_name in sorted(attributes):
             _, attr_shape = attributes[attr_name]
-            attribute_section = section.add_new_section(attr_name)
             attribute_list.append(attr_name)
+            # 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)
             document_attribute(
                 section=attribute_section,
                 service_name=self._service_name,
@@ -197,6 +218,16 @@ def _add_attributes(self, section):
                 event_emitter=self._resource.meta.client.meta.events,
                 attr_model=attr_shape,
             )
+            # Write attributes in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<attribute_name>.rst
+            attributes_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            attribute_doc.write_to_file(attributes_dir_path, attr_name)
+        if attributes:
+            self._add_overview_of_member_type(section, 'attributes')
 
     def _add_references(self, section):
         section = section.add_new_section('references')
@@ -213,36 +244,57 @@ def _add_references(self, section):
                 intro_link='references_intro',
             )
             self.member_map['references'] = reference_list
+            self._add_overview_of_member_type(section, 'references')
         for reference in references:
-            reference_section = section.add_new_section(reference.name)
             reference_list.append(reference.name)
+            # 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)
             document_reference(
                 section=reference_section, reference_model=reference
             )
+            # Write references in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<reference_name>.rst
+            references_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            reference_doc.write_to_file(references_dir_path, reference.name)
+        if references:
+            self._add_overview_of_member_type(section, 'references')
 
     def _add_actions(self, section):
         section = section.add_new_section('actions')
         actions = self._resource.meta.resource_model.actions
         if actions:
-            documenter = ActionDocumenter(self._resource)
+            documenter = ActionDocumenter(self._resource, self._root_docs_path)
             documenter.member_map = self.member_map
             documenter.document_actions(section)
+            self._add_overview_of_member_type(section, 'actions')
 
     def _add_sub_resources(self, section):
         section = section.add_new_section('sub-resources')
         sub_resources = self._resource.meta.resource_model.subresources
         if sub_resources:
-            documenter = SubResourceDocumenter(self._resource)
+            documenter = SubResourceDocumenter(
+                self._resource, self._root_docs_path
+            )
             documenter.member_map = self.member_map
             documenter.document_sub_resources(section)
+            self._add_overview_of_member_type(section, 'sub-resources')
 
     def _add_collections(self, section):
         section = section.add_new_section('collections')
         collections = self._resource.meta.resource_model.collections
         if collections:
-            documenter = CollectionDocumenter(self._resource)
+            documenter = CollectionDocumenter(
+                self._resource, self._root_docs_path
+            )
             documenter.member_map = self.member_map
             documenter.document_collections(section)
+            self._add_overview_of_member_type(section, 'collections')
 
     def _add_waiters(self, section):
         section = section.add_new_section('waiters')
@@ -252,10 +304,21 @@ def _add_waiters(self, section):
                 self._service_name
             )
             documenter = WaiterResourceDocumenter(
-                self._resource, service_waiter_model
+                self._resource, service_waiter_model, self._root_docs_path
             )
             documenter.member_map = self.member_map
             documenter.document_resource_waiters(section)
+            self._add_overview_of_member_type(section, 'waiters')
+
+    def _add_resource_note(self, section):
+        section = section.add_new_section('feature-freeze')
+        section.style.start_note()
+        section.write(
+            "Before using anything on this page, please refer to the resources "
+            ":doc:`user guide <../../../../guide/resources>` for the most recent "
+            "guidance on using resources."
+        )
+        section.style.end_note()
 
 
 class ServiceResourceDocumenter(ResourceDocumenter):
diff --git a/boto3/docs/service.py b/boto3/docs/service.py
index 56a4e6360d..6d3b31d5d6 100644
--- a/boto3/docs/service.py
+++ b/boto3/docs/service.py
@@ -26,12 +26,13 @@ class ServiceDocumenter(BaseServiceDocumenter):
     # The path used to find examples
     EXAMPLE_PATH = os.path.join(os.path.dirname(boto3.__file__), 'examples')
 
-    def __init__(self, service_name, session):
+    def __init__(self, service_name, session, root_docs_path):
         super().__init__(
             service_name=service_name,
             # I know that this is an internal attribute, but the botocore session
             # is needed to load the paginator and waiter models.
             session=session._session,
+            root_docs_path=root_docs_path,
         )
         self._boto3_session = session
         self._client = self._boto3_session.client(service_name)
@@ -44,10 +45,14 @@ def __init__(self, service_name, session):
             'client',
             'paginators',
             'waiters',
-            'service-resource',
             'resources',
             'examples',
         ]
+        self._root_docs_path = root_docs_path
+        self._USER_GUIDE_LINK = (
+            'https://boto3.amazonaws.com/'
+            'v1/documentation/api/latest/guide/resources.html'
+        )
 
     def document_service(self):
         """Documents an entire service.
@@ -64,10 +69,7 @@ def document_service(self):
         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.resource_section(doc_structure.get_section('resources'))
         self._document_examples(doc_structure.get_section('examples'))
         return doc_structure.flush_structure()
 
@@ -78,12 +80,52 @@ def client_api(self, section):
         except DataNotFoundError:
             pass
 
-        Boto3ClientDocumenter(self._client, examples).document_client(section)
+        Boto3ClientDocumenter(
+            self._client, self._root_docs_path, examples
+        ).document_client(section)
+
+    def resource_section(self, section):
+        section.style.h2('Resources')
+        section.style.new_line()
+        section.write(
+            'Resources are available in boto3 via the '
+            '``resource`` method. For more detailed instructions '
+            'and examples on the usage of resources, see the '
+            'resources '
+        )
+        section.style.external_link(
+            title='user guide',
+            link=self._USER_GUIDE_LINK,
+        )
+        section.write('.')
+        section.style.new_line()
+        section.style.new_line()
+        section.write('The available resources are:')
+        section.style.new_line()
+        section.style.toctree()
+        self._document_service_resource(section)
+        self._document_resources(section)
 
     def _document_service_resource(self, section):
+        # Create a new DocumentStructure for each Service Resource and add contents.
+        service_resource_doc = DocumentStructure(
+            'service-resource', target='html'
+        )
         ServiceResourceDocumenter(
-            self._service_resource, self._session
-        ).document_resource(section)
+            self._service_resource, self._session, self._root_docs_path
+        ).document_resource(service_resource_doc)
+        # Write collections in individual/nested files.
+        # Path: <root>/reference/services/<service>/<resource_name>/<collection_name>.rst
+        resource_name = self._service_resource.meta.resource_model.name
+        if resource_name == self._service_name:
+            resource_name = 'service-resource'
+        service_resource_dir_path = os.path.join(
+            self._root_docs_path,
+            f'{self._service_name}',
+            f'{resource_name.lower()}',
+        )
+        service_resource_doc.write_to_file(service_resource_dir_path, 'index')
+        section.style.tocitem(f'{self._service_name}/{resource_name}/index')
 
     def _document_resources(self, section):
         temp_identifier_value = 'foo'
@@ -113,8 +155,24 @@ def _document_resources(self, section):
             for _ in identifiers:
                 args.append(temp_identifier_value)
             resource = resource_cls(*args, client=self._client)
-            ResourceDocumenter(resource, self._session).document_resource(
-                section.add_new_section(resource.meta.resource_model.name)
+            # Create a new DocumentStructure for each Resource and add contents.
+            resource_name = resource.meta.resource_model.name.lower()
+            resource_doc = DocumentStructure(resource_name, target='html')
+            ResourceDocumenter(
+                resource, self._session, self._root_docs_path
+            ).document_resource(
+                resource_doc.add_new_section(resource.meta.resource_model.name)
+            )
+            # Write collections in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<index>.rst
+            service_resource_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{resource_name}',
+            )
+            resource_doc.write_to_file(service_resource_dir_path, 'index')
+            section.style.tocitem(
+                f'{self._service_name}/{resource_name}/index'
             )
 
     def _get_example_file(self):
diff --git a/boto3/docs/subresource.py b/boto3/docs/subresource.py
index e22311c814..b0c4ff4a69 100644
--- a/boto3/docs/subresource.py
+++ b/boto3/docs/subresource.py
@@ -10,10 +10,13 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+
 from botocore import xform_name
+from botocore.docs.bcdoc.restdoc import DocumentStructure
 from botocore.utils import get_service_module_name
 
-from boto3.docs.base import BaseDocumenter
+from boto3.docs.base import NestedDocumenter
 from boto3.docs.utils import (
     add_resource_type_overview,
     get_identifier_args_for_signature,
@@ -22,7 +25,7 @@
 )
 
 
-class SubResourceDocumenter(BaseDocumenter):
+class SubResourceDocumenter(NestedDocumenter):
     def document_sub_resources(self, section):
         add_resource_type_overview(
             section=section,
@@ -41,8 +44,15 @@ def document_sub_resources(self, section):
         sub_resources_list = []
         self.member_map['sub-resources'] = sub_resources_list
         for sub_resource in sub_resources:
-            sub_resource_section = section.add_new_section(sub_resource.name)
             sub_resources_list.append(sub_resource.name)
+            # Create a new DocumentStructure for each sub_resource and add contents.
+            sub_resource_doc = DocumentStructure(
+                sub_resource.name, target='html'
+            )
+            sub_resource_doc.add_title_section(sub_resource.name)
+            sub_resource_section = sub_resource_doc.add_new_section(
+                sub_resource.name
+            )
             document_sub_resource(
                 section=sub_resource_section,
                 resource_name=self._resource_name,
@@ -50,6 +60,17 @@ def document_sub_resources(self, section):
                 service_model=self._service_model,
             )
 
+            # Write sub_resources in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<sub_resource_name>.rst
+            sub_resources_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            sub_resource_doc.write_to_file(
+                sub_resources_dir_path, sub_resource.name
+            )
+
 
 def document_sub_resource(
     section,
diff --git a/boto3/docs/utils.py b/boto3/docs/utils.py
index 13a098dd61..0830af5052 100644
--- a/boto3/docs/utils.py
+++ b/boto3/docs/utils.py
@@ -71,10 +71,7 @@ def add_resource_type_overview(
     section, resource_type, description, intro_link=None
 ):
     section.style.new_line()
-    section.write('.. rst-class:: admonition-title')
-    section.style.new_line()
-    section.style.new_line()
-    section.write(resource_type)
+    section.style.h3(resource_type)
     section.style.new_line()
     section.style.new_line()
     section.write(description)
diff --git a/boto3/docs/waiter.py b/boto3/docs/waiter.py
index 255d850bc3..559447cab5 100644
--- a/boto3/docs/waiter.py
+++ b/boto3/docs/waiter.py
@@ -10,20 +10,23 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+
 from botocore import xform_name
+from botocore.docs.bcdoc.restdoc import DocumentStructure
 from botocore.docs.method import document_model_driven_method
 from botocore.utils import get_service_module_name
 
-from boto3.docs.base import BaseDocumenter
+from boto3.docs.base import NestedDocumenter
 from boto3.docs.utils import (
     add_resource_type_overview,
     get_resource_ignore_params,
 )
 
 
-class WaiterResourceDocumenter(BaseDocumenter):
-    def __init__(self, resource, service_waiter_model):
-        super().__init__(resource)
+class WaiterResourceDocumenter(NestedDocumenter):
+    def __init__(self, resource, service_waiter_model, root_docs_path):
+        super().__init__(resource, root_docs_path)
         self._service_waiter_model = service_waiter_model
 
     def document_resource_waiters(self, section):
@@ -40,8 +43,11 @@ def document_resource_waiters(self, section):
         waiter_list = []
         self.member_map['waiters'] = waiter_list
         for waiter in waiters:
-            waiter_section = section.add_new_section(waiter.name)
             waiter_list.append(waiter.name)
+            # 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)
             document_resource_waiter(
                 section=waiter_section,
                 resource_name=self._resource_name,
@@ -50,6 +56,14 @@ def document_resource_waiters(self, section):
                 resource_waiter_model=waiter,
                 service_waiter_model=self._service_waiter_model,
             )
+            # Write waiters in individual/nested files.
+            # Path: <root>/reference/services/<service>/<resource_name>/<waiter_name>.rst
+            waiters_dir_path = os.path.join(
+                self._root_docs_path,
+                f'{self._service_name}',
+                f'{self._resource_sub_path}',
+            )
+            waiter_doc.write_to_file(waiters_dir_path, waiter.name)
 
 
 def document_resource_waiter(
diff --git a/docs/source/_static/js/custom.js b/docs/source/_static/js/custom.js
new file mode 100644
index 0000000000..3a5b1be1fe
--- /dev/null
+++ b/docs/source/_static/js/custom.js
@@ -0,0 +1,73 @@
+/*
+Copyright Amazon.com, Inc. or its affiliates. All Rights Reserved.
+
+Licensed under the Apache License, Version 2.0 (the "License").
+You may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+	http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.
+*/
+const nonResourceSubHeadings = [
+	'client',
+	'waiters',
+	'paginators',
+	'resources',
+	'examples'
+];
+// Checks if an html doc name matches a service class name.
+function isValidServiceName(docName, serviceClassName) {
+	const newDocName = docName.replaceAll('-', '').toLowerCase();
+	return newDocName === serviceClassName;
+}
+// Checks if all elements of the split fragment are valid.
+// Fragment items should only contain alphanumerics, hyphens, & underscores.
+// A fragment should also only be redirected if it contain 3-5 items.
+function isValidFragment(splitFragment) {
+	const regex = /^[a-z0-9-_]+$/i;
+	for (index in splitFragment) {
+		if (!regex.test(splitFragment[index])) {
+			return false;
+		}
+	}
+	return splitFragment.length >= 1 && splitFragment.length < 5;
+}
+// Checks if a name is a possible resource name.
+function isValidResource(name, serviceDocName) {
+	return name.replaceAll('-', '') !== serviceDocName && !nonResourceSubHeadings.includes(name);
+}
+// Reroutes previously existing links to the new path.
+// Old: <root_url>/reference/services/s3.html#S3.Client.delete_bucket
+// New: <root_url>/reference/services/s3/client/delete_bucket.html
+// This must be done client side since the fragment (#S3.Client.delete_bucket) is never
+// passed to the server.
+(function () {
+	const currentPath = window.location.pathname.split('/');
+	const fragment = window.location.hash.substring(1);
+	const splitFragment = fragment.split('.').map(part => part.replace(/serviceresource/i, 'service-resource'));
+	// Only redirect when viewing a top-level service page.
+	if (isValidFragment(splitFragment) && currentPath[currentPath.length - 2] === 'services') {
+		const serviceDocName = currentPath[currentPath.length - 1].replace('.html', '');
+		if (splitFragment.length > 1) {
+			splitFragment[0] = splitFragment[0].toLowerCase();
+			splitFragment[1] = splitFragment[1].toLowerCase();
+		}
+		let newPath;
+		if (splitFragment.length >= 3 && isValidServiceName(serviceDocName, splitFragment[0])) {
+			splitFragment[0] = serviceDocName;
+			newPath = `${ splitFragment.slice(0, 3).join('/') }.html#${ splitFragment.length > 3 ? fragment : '' }`;
+		} else if (splitFragment.length == 2 && isValidResource(splitFragment[1].toLowerCase(), serviceDocName)) {
+			newPath = `${ splitFragment.join('/') }/index.html#${ fragment }`;
+		} else if (splitFragment.length == 1 && isValidResource(splitFragment[0], serviceDocName)) {
+			newPath = `${ serviceDocName }/${ splitFragment.join('/') }/index.html`;
+		} else {
+			return;
+		}
+		window.location.assign(newPath);
+	}
+}());
diff --git a/docs/source/_templates/layout.html b/docs/source/_templates/layout.html
index f7503fe37d..2241114db3 100644
--- a/docs/source/_templates/layout.html
+++ b/docs/source/_templates/layout.html
@@ -7,6 +7,7 @@
 
 {%- block footer %}
 <div class="footer">
+    <script type="text/javascript" src="{{ pathto('_static/js/custom.js',1 ) }}"></script>
     <script type="text/javascript" src="{{ pathto('_static/shortbreadv1.js',1 ) }}"></script>
     <script type="text/javascript">
             const shortbread = AWSCShortbread({
diff --git a/docs/source/conf.py b/docs/source/conf.py
index 769c37a362..96f13ce608 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -12,6 +12,7 @@
 # All configuration values have a default; values that are commented out
 # serve to show the default.
 
+import datetime
 import os
 
 import boto3
@@ -51,7 +52,8 @@
 
 # General information about the project.
 project = 'Boto3 Docs'
-copyright = '2022, Amazon Web Services, Inc'
+current_year = datetime.date.today().year
+copyright = f'{current_year}, Amazon Web Services, Inc'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the
diff --git a/tests/functional/docs/__init__.py b/tests/functional/docs/__init__.py
index b62ab16fdd..b126ea0461 100644
--- a/tests/functional/docs/__init__.py
+++ b/tests/functional/docs/__init__.py
@@ -10,10 +10,23 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+import shutil
+import tempfile
+
 from tests import unittest
 
 
 class BaseDocsFunctionalTests(unittest.TestCase):
+    def setUp(self):
+        self.docs_root_dir = tempfile.mkdtemp()
+        self.root_services_path = os.path.join(
+            self.docs_root_dir, 'reference', 'services'
+        )
+
+    def tearDown(self):
+        shutil.rmtree(self.docs_root_dir)
+
     def assert_contains_lines_in_order(self, lines, contents):
         for line in lines:
             assert line in contents
@@ -73,3 +86,13 @@ def get_response_parameter_document_block(self, param_name, contents):
         contents = contents[start_index:]
         end_index = contents.find('- **', len(start_param_document))
         return contents[:end_index]
+
+    def get_nested_file_contents(self, service_name, sub_folder, file_name):
+        service_file_path = os.path.join(
+            self.root_services_path,
+            service_name,
+            sub_folder,
+            f'{file_name}.rst',
+        )
+        with open(service_file_path, 'rb') as f:
+            return f.read().decode('utf-8')
diff --git a/tests/functional/docs/test_dynamodb.py b/tests/functional/docs/test_dynamodb.py
index 032a9eae85..fb5e41f6cb 100644
--- a/tests/functional/docs/test_dynamodb.py
+++ b/tests/functional/docs/test_dynamodb.py
@@ -17,8 +17,11 @@
 
 class TestDynamoDBCustomizations(BaseDocsFunctionalTests):
     def setUp(self):
+        super().setUp()
         self.documenter = ServiceDocumenter(
-            'dynamodb', session=Session(region_name='us-east-1')
+            'dynamodb',
+            session=Session(region_name='us-east-1'),
+            root_docs_path=self.root_services_path,
         )
         self.generated_contents = self.documenter.document_service()
         self.generated_contents = self.generated_contents.decode('utf-8')
@@ -26,27 +29,40 @@ def setUp(self):
     def test_batch_writer_is_documented(self):
         self.assert_contains_lines_in_order(
             [
-                '.. py:class:: DynamoDB.Table(name)',
-                '  *   :py:meth:`batch_writer()`',
-                '  .. py:method:: batch_writer(overwrite_by_pkeys=None)',
+                '=========',
+                'Resources',
+                '=========',
+                'The available resources are:',
+                '  dynamodb/table/index',
             ],
             self.generated_contents,
         )
-
-    def test_document_interface_is_documented(self):
-        contents = self.get_class_document_block(
-            'DynamoDB.Table', self.generated_contents
+        self.assert_contains_lines_in_order(
+            [
+                '.. py:class:: DynamoDB.Table(name)',
+                '  batch_writer',
+            ],
+            self.get_nested_file_contents('dynamodb', 'table', 'index'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                '************\nbatch_writer\n************',
+                '.. py:method:: batch_writer(overwrite_by_pkeys=None)',
+            ],
+            self.get_nested_file_contents('dynamodb', 'table', 'batch_writer'),
         )
 
-        # Take an arbitrary method that uses the customization.
-        method_contents = self.get_method_document_block('put_item', contents)
-
-        # Make sure the request syntax is as expected.
-        request_syntax_contents = self.get_request_syntax_document_block(
-            method_contents
+    def test_document_interface_is_documented(self):
+        put_item_content = self.get_nested_file_contents(
+            'dynamodb', 'table', 'put_item'
         )
         self.assert_contains_lines_in_order(
             [
+                '********',
+                'put_item',
+                '********',
+                '.. py:method:: put_item(**kwargs)',
+                # Make sure the request syntax is as expected.
                 'response = table.put_item(',
                 'Item={',
                 (
@@ -68,34 +84,7 @@ def test_document_interface_is_documented(self):
                     '|True|None|set([\'string\'])|set([123])|'
                     'set([Binary(b\'bytes\')])|[]|{},'
                 ),
-            ],
-            request_syntax_contents,
-        )
-
-        # Make sure the response syntax is as expected.
-        response_syntax_contents = self.get_response_syntax_document_block(
-            method_contents
-        )
-        self.assert_contains_lines_in_order(
-            [
-                '{',
-                '\'Attributes\': {',
-                (
-                    '\'string\': \'string\'|123|'
-                    'Binary(b\'bytes\')|True|None|set([\'string\'])|'
-                    'set([123])|set([Binary(b\'bytes\')])|[]|{}'
-                ),
-                '},',
-            ],
-            response_syntax_contents,
-        )
-
-        # Make sure the request parameter is documented correctly.
-        request_param_contents = self.get_request_parameter_document_block(
-            'Item', method_contents
-        )
-        self.assert_contains_lines_in_order(
-            [
+                # Make sure the request parameter is documented correctly.
                 ':type Item: dict',
                 ':param Item: **[REQUIRED]**',
                 '- *(string) --*',
@@ -104,16 +93,16 @@ def test_document_interface_is_documented(self):
                     'attribute. The valid value types are listed in the '
                     ':ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`.'
                 ),
-            ],
-            request_param_contents,
-        )
-
-        # Make sure the response parameter is documented correctly.
-        response_param_contents = self.get_response_parameter_document_block(
-            'Attributes', method_contents
-        )
-        self.assert_contains_lines_in_order(
-            [
+                # Make sure the response syntax is as expected.
+                '{',
+                '\'Attributes\': {',
+                (
+                    '\'string\': \'string\'|123|'
+                    'Binary(b\'bytes\')|True|None|set([\'string\'])|'
+                    'set([123])|set([Binary(b\'bytes\')])|[]|{}'
+                ),
+                '},',
+                # Make sure the response parameter is documented correctly.
                 '- **Attributes** *(dict) --*',
                 '- *(string) --*',
                 (
@@ -122,33 +111,20 @@ def test_document_interface_is_documented(self):
                     ':ref:`DynamoDB Reference Guide<ref_valid_dynamodb_types>`.'
                 ),
             ],
-            response_param_contents,
+            put_item_content,
         )
 
     def test_conditions_is_documented(self):
-        contents = self.get_class_document_block(
-            'DynamoDB.Table', self.generated_contents
-        )
-
-        # Take an arbitrary method that uses the customization.
-        method_contents = self.get_method_document_block('query', contents)
-
-        # Make sure the request syntax is as expected.
-        request_syntax_contents = self.get_request_syntax_document_block(
-            method_contents
+        query_contents = self.get_nested_file_contents(
+            'dynamodb', 'table', 'query'
         )
         self.assert_contains_lines_in_order(
             [
+                # Make sure the request syntax is as expected.
                 'response = table.query(',
                 ('FilterExpression=Attr(\'myattribute\').' 'eq(\'myvalue\'),'),
                 ('KeyConditionExpression=Key(\'mykey\')' '.eq(\'myvalue\'),'),
-            ],
-            request_syntax_contents,
-        )
-
-        # Make sure the request parameter is documented correctly.
-        self.assert_contains_lines_in_order(
-            [
+                # Make sure the request parameter is documented correctly.
                 (
                     ':type FilterExpression: condition from '
                     ':py:class:`boto3.dynamodb.conditions.Attr` method'
@@ -168,5 +144,5 @@ def test_conditions_is_documented(self):
                     ':ref:`DynamoDB Reference Guide<ref_dynamodb_conditions>`.'
                 ),
             ],
-            method_contents,
+            query_contents,
         )
diff --git a/tests/functional/docs/test_ec2.py b/tests/functional/docs/test_ec2.py
index d1d7551b70..cd01723b78 100644
--- a/tests/functional/docs/test_ec2.py
+++ b/tests/functional/docs/test_ec2.py
@@ -17,24 +17,40 @@
 
 class TestInstanceDeleteTags(BaseDocsFunctionalTests):
     def setUp(self):
+        super().setUp()
         self.documenter = ServiceDocumenter(
-            'ec2', session=Session(region_name='us-east-1')
+            'ec2',
+            session=Session(region_name='us-east-1'),
+            root_docs_path=self.root_services_path,
         )
         self.generated_contents = self.documenter.document_service()
         self.generated_contents = self.generated_contents.decode('utf-8')
 
     def test_delete_tags_method_is_documented(self):
-        contents = self.get_class_document_block(
-            'EC2.Instance', self.generated_contents
+        self.assert_contains_lines_in_order(
+            [
+                '=========',
+                'Resources',
+                '=========',
+                'The available resources are:',
+                '  ec2/instance/index',
+            ],
+            self.generated_contents,
         )
-        method_contents = self.get_method_document_block(
-            'delete_tags', contents
+        self.assert_contains_lines_in_order(
+            [
+                '.. py:class:: EC2.Instance',
+                '  delete_tags',
+            ],
+            self.get_nested_file_contents('ec2', 'instance', 'index'),
         )
         self.assert_contains_lines_in_order(
             [
+                'delete_tags',
+                '.. py:method:: delete_tags(**kwargs)',
                 'response = instance.delete_tags(',
                 'DryRun=True|False,',
                 'Tags=[',
             ],
-            method_contents,
+            self.get_nested_file_contents('ec2', 'instance', 'delete_tags'),
         )
diff --git a/tests/functional/docs/test_s3.py b/tests/functional/docs/test_s3.py
index 09f834f3d0..b53b7ec382 100644
--- a/tests/functional/docs/test_s3.py
+++ b/tests/functional/docs/test_s3.py
@@ -17,20 +17,45 @@
 
 class TestS3Customizations(BaseDocsFunctionalTests):
     def setUp(self):
+        super().setUp()
         self.documenter = ServiceDocumenter(
-            's3', session=Session(region_name='us-east-1')
+            's3',
+            session=Session(region_name='us-east-1'),
+            root_docs_path=self.root_services_path,
         )
         self.generated_contents = self.documenter.document_service()
         self.generated_contents = self.generated_contents.decode('utf-8')
 
     def test_file_transfer_methods_are_documented(self):
+        self.assert_contains_lines_in_order(
+            [
+                '=========',
+                'Resources',
+                '=========',
+                'The available resources are:',
+                '  s3/service-resource/index',
+            ],
+            self.generated_contents,
+        )
         self.assert_contains_lines_in_order(
             [
                 '.. py:class:: S3.Client',
-                '  *   :py:meth:`~S3.Client.download_file`',
-                '  *   :py:meth:`~S3.Client.upload_file`',
-                '  .. py:method:: download_file(',
-                '  .. py:method:: upload_file(',
+                '  s3/client/download_file',
+                '  s3/client/upload_file',
             ],
             self.generated_contents,
         )
+        self.assert_contains_lines_in_order(
+            [
+                'download_file',
+                '.. py:method:: download_file(',
+            ],
+            self.get_nested_file_contents('s3', 'client', 'download_file'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'upload_file',
+                '.. py:method:: 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 30d9326ec8..a1b3e10544 100644
--- a/tests/functional/docs/test_smoke.py
+++ b/tests/functional/docs/test_smoke.py
@@ -10,6 +10,10 @@
 # distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
 # ANY KIND, either express or implied. See the License for the specific
 # language governing permissions and limitations under the License.
+import os
+import shutil
+import tempfile
+
 import botocore.session
 import pytest
 from botocore import xform_name
@@ -18,6 +22,9 @@
 import boto3
 from boto3.docs.service import ServiceDocumenter
 
+DOCS_ROOT_DIR = None
+ROOT_SERVICES_PATH = None
+
 
 @pytest.fixture
 def botocore_session():
@@ -30,8 +37,16 @@ def boto3_session():
 
 
 def all_services():
+    # Create temporary directory before testing.
+    global DOCS_ROOT_DIR, ROOT_SERVICES_PATH
+    DOCS_ROOT_DIR = tempfile.mkdtemp()
+    ROOT_SERVICES_PATH = os.path.join(
+        tempfile.mkdtemp(), 'reference', 'services'
+    )
     session = boto3.Session(region_name='us-east-1')
     yield from session.get_available_services()
+    # Clean up temporary directory after testing.
+    shutil.rmtree(DOCS_ROOT_DIR)
 
 
 @pytest.fixture
@@ -45,7 +60,7 @@ def test_documentation(
     boto3_session, botocore_session, available_resources, service_name
 ):
     generated_docs = ServiceDocumenter(
-        service_name, session=boto3_session
+        service_name, session=boto3_session, root_docs_path=ROOT_SERVICES_PATH
     ).document_service()
     generated_docs = generated_docs.decode('utf-8')
     client = boto3.client(service_name, 'us-east-1')
@@ -68,12 +83,13 @@ def test_documentation(
     # If the client can paginate, make sure the paginators are documented.
     try:
         paginator_model = botocore_session.get_paginator_model(service_name)
-        _assert_has_paginator_documentation(
-            generated_docs,
-            service_name,
-            client,
-            sorted(paginator_model._paginator_config),
-        )
+        if paginator_model._paginator_config:
+            _assert_has_paginator_documentation(
+                generated_docs,
+                service_name,
+                client,
+                sorted(paginator_model._paginator_config),
+            )
     except DataNotFoundError:
         pass
 
@@ -108,13 +124,19 @@ def _assert_has_client_documentation(generated_docs, service_name, client):
         '  A low-level client representing',
         '    import boto3',
         '    client = boto3.client(\'%s\')' % service_name,
-        '  These are the available methods:',
-        '  *   :py:meth:`~%s.Client.get_paginator`' % class_name,
-        '  *   :py:meth:`~%s.Client.get_waiter`' % class_name,
-        '  .. py:method:: get_paginator(operation_name)',
-        '  .. py:method:: get_waiter(waiter_name)',
+        'These are the available methods:',
+        '  %s/client/get_paginator' % service_name,
+        '  %s/client/get_waiter' % service_name,
     ]
     _assert_contains_lines_in_order(ref_lines, generated_docs)
+    for method_name in ['get_paginator', 'get_waiter']:
+        _assert_contains_lines_in_order(
+            [
+                f'{method_name}',
+                f'.. py:method:: {method_name}(',
+            ],
+            get_nested_file_contents(service_name, 'client', method_name),
+        )
 
 
 def _assert_has_paginator_documentation(
@@ -127,19 +149,20 @@ def _assert_has_paginator_documentation(
         'The available paginators are:',
     ]
     for paginator_name in paginator_names:
-        ref_lines.append(
-            '* :py:class:`{}.Paginator.{}`'.format(
-                client.__class__.__name__, paginator_name
-            )
-        )
+        ref_lines.append(f'  {service_name}/paginator/{paginator_name}')
 
     for paginator_name in paginator_names:
-        ref_lines.append(
-            '.. py:class:: {}.Paginator.{}'.format(
-                client.__class__.__name__, paginator_name
-            )
+        _assert_contains_lines_in_order(
+            [
+                '.. py:class:: {}.Paginator.{}'.format(
+                    client.__class__.__name__, paginator_name
+                ),
+                '  .. py:method:: paginate(',
+            ],
+            get_nested_file_contents(
+                service_name, 'paginator', paginator_name
+            ),
         )
-        ref_lines.append('  .. py:method:: paginate(')
 
     _assert_contains_lines_in_order(ref_lines, generated_docs)
 
@@ -149,28 +172,35 @@ def _assert_has_waiter_documentation(
 ):
     ref_lines = ['=======', 'Waiters', '=======', 'The available waiters are:']
     for waiter_name in waiter_model.waiter_names:
-        ref_lines.append(
-            '* :py:class:`{}.Waiter.{}`'.format(
-                client.__class__.__name__, waiter_name
-            )
-        )
+        ref_lines.append(f'  {service_name}/waiter/{waiter_name}')
 
     for waiter_name in waiter_model.waiter_names:
-        ref_lines.append(
-            '.. py:class:: {}.Waiter.{}'.format(
-                client.__class__.__name__, waiter_name
-            )
-        )
-        ref_lines.append(
-            '    waiter = client.get_waiter(\'%s\')' % xform_name(waiter_name)
+        _assert_contains_lines_in_order(
+            [
+                '.. py:class:: {}.Waiter.{}'.format(
+                    client.__class__.__name__, waiter_name
+                ),
+                '    waiter = client.get_waiter(\'%s\')'
+                % xform_name(waiter_name),
+                '  .. py:method:: wait(',
+            ],
+            get_nested_file_contents(service_name, 'waiter', waiter_name),
         )
-        ref_lines.append('  .. py:method:: wait(')
 
     _assert_contains_lines_in_order(ref_lines, generated_docs)
 
 
 def _assert_has_resource_documentation(generated_docs, service_name, resource):
     ref_lines = [
+        '=======',
+        'Resources',
+        '=======',
+        'The available resources are:',
+    ]
+    ref_lines.append(f'  {service_name}/service-resource/index')
+    _assert_contains_lines_in_order(ref_lines, generated_docs)
+
+    service_resource_ref_lines = [
         '================',
         'Service Resource',
         '================',
@@ -180,4 +210,18 @@ def _assert_has_resource_documentation(generated_docs, service_name, resource):
         '    import boto3',
         f'    {service_name} = boto3.resource(\'{service_name}\')',
     ]
-    _assert_contains_lines_in_order(ref_lines, generated_docs)
+    _assert_contains_lines_in_order(
+        service_resource_ref_lines,
+        get_nested_file_contents(service_name, 'service-resource', 'index'),
+    )
+
+
+def get_nested_file_contents(service_name, sub_folder, file_name):
+    service_file_path = os.path.join(
+        ROOT_SERVICES_PATH,
+        service_name,
+        sub_folder,
+        f'{file_name}.rst',
+    )
+    with open(service_file_path, 'rb') as f:
+        return f.read().decode('utf-8')
diff --git a/tests/unit/docs/__init__.py b/tests/unit/docs/__init__.py
index 753275ebe0..a50934c8be 100644
--- a/tests/unit/docs/__init__.py
+++ b/tests/unit/docs/__init__.py
@@ -45,6 +45,10 @@ def setUp(self):
         self.example_model_file = os.path.join(
             self.version_dirs, 'examples-1.json'
         )
+        self.docs_root_dir = tempfile.mkdtemp()
+        self.root_services_path = os.path.join(
+            self.docs_root_dir, 'reference', 'services'
+        )
 
         self.json_model = {}
         self.waiter_json_model = {}
@@ -53,12 +57,13 @@ def setUp(self):
         self._setup_models()
 
         self.doc_name = 'MyDoc'
-        self.doc_structure = DocumentStructure(self.doc_name)
+        self.doc_structure = DocumentStructure(self.doc_name, target='html')
 
         self.setup_client_and_resource()
 
     def tearDown(self):
         shutil.rmtree(self.root_dir)
+        shutil.rmtree(self.docs_root_dir)
 
     def setup_client_and_resource(self):
         self._write_models()
@@ -71,6 +76,13 @@ def setup_client_and_resource(self):
         self.client = self.session.client('myservice', 'us-east-1')
         self.resource = self.session.resource('myservice', 'us-east-1')
 
+    def get_nested_service_contents(self, service, type, name):
+        service_file_path = os.path.join(
+            self.root_services_path, service, type, f'{name}.rst'
+        )
+        with open(service_file_path, 'rb') as f:
+            return f.read().decode('utf-8')
+
     def _setup_models(self):
         self.json_model = {
             'metadata': {
diff --git a/tests/unit/docs/test_action.py b/tests/unit/docs/test_action.py
index e0e6194034..9543985af7 100644
--- a/tests/unit/docs/test_action.py
+++ b/tests/unit/docs/test_action.py
@@ -16,10 +16,22 @@
 
 class TestActionDocumenter(BaseDocsTest):
     def test_document_service_resource_actions(self):
-        action_documenter = ActionDocumenter(self.resource)
+        action_documenter = ActionDocumenter(
+            self.resource, self.root_services_path
+        )
         action_documenter.document_actions(self.doc_structure)
         self.assert_contains_lines_in_order(
             [
+                '-------\nActions\n-------',
+                'Actions call operations on resources.  They may',
+                'automatically handle the passing in of arguments set',
+                'from identifiers and some attributes.',
+                'For more information about actions refer to the ',
+            ]
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'sample_operation',
                 '.. py:method:: sample_operation(**kwargs)',
                 '  **Request Syntax**',
                 '  ::',
@@ -43,15 +55,30 @@ def test_document_service_resource_actions(self):
                 '    - *(dict) --*',
                 '      - **Foo** *(string) --* Documents Foo',
                 '      - **Bar** *(string) --* Documents Bar',
-            ]
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'sample_operation'
+            ),
         )
 
     def test_document_nonservice_resource_actions(self):
         subresource = self.resource.Sample('mysample')
-        action_documenter = ActionDocumenter(subresource)
+        action_documenter = ActionDocumenter(
+            subresource, self.root_services_path
+        )
         action_documenter.document_actions(self.doc_structure)
         self.assert_contains_lines_in_order(
             [
+                '-------\nActions\n-------',
+                'Actions call operations on resources.  They may',
+                'automatically handle the passing in of arguments set',
+                'from identifiers and some attributes.',
+                'For more information about actions refer to the ',
+            ]
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'load',
                 '.. py:method:: load()',
                 (
                     '  Calls :py:meth:`MyService.Client.sample_operation` to update '
@@ -61,6 +88,12 @@ def test_document_nonservice_resource_actions(self):
                 '  ::',
                 '    sample.load()',
                 '  :returns: None',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'load'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'operate',
                 '.. py:method:: operate(**kwargs)',
                 '  **Request Syntax** ',
                 '  ::',
@@ -82,6 +115,12 @@ def test_document_nonservice_resource_actions(self):
                 '    - *(dict) --* ',
                 '      - **Foo** *(string) --* Documents Foo',
                 '      - **Bar** *(string) --* Documents Bar',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'operate'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'reload',
                 '.. py:method:: reload()',
                 (
                     '  Calls :py:meth:`MyService.Client.sample_operation` to update '
@@ -91,5 +130,18 @@ def test_document_nonservice_resource_actions(self):
                 '  ::',
                 '    sample.reload()',
                 '  :returns: None',
-            ]
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'reload'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'get_available_subresources',
+                '.. py:method:: 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',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'sample', 'get_available_subresources'
+            ),
         )
diff --git a/tests/unit/docs/test_client.py b/tests/unit/docs/test_client.py
index f94af36aec..58fe853793 100644
--- a/tests/unit/docs/test_client.py
+++ b/tests/unit/docs/test_client.py
@@ -17,7 +17,9 @@
 class TestBoto3ClientDocumenter(BaseDocsTest):
     def setUp(self):
         super().setUp()
-        self.client_documenter = Boto3ClientDocumenter(self.client)
+        self.client_documenter = Boto3ClientDocumenter(
+            self.client, self.root_services_path
+        )
 
     def test_document_client(self):
         self.client_documenter.document_client(self.doc_structure)
@@ -31,36 +33,71 @@ def test_document_client(self):
                 '  ::',
                 '    import boto3',
                 '    client = boto3.client(\'myservice\')',
-                '  These are the available methods:',
-                '  *   :py:meth:`~MyService.Client.can_paginate`',
-                '  *   :py:meth:`~MyService.Client.get_paginator`',
-                '  *   :py:meth:`~MyService.Client.get_waiter`',
-                '  *   :py:meth:`~MyService.Client.sample_operation`',
-                '  .. py:method:: can_paginate(operation_name)',
-                '  .. py:method:: get_paginator(operation_name)',
-                '  .. py:method:: get_waiter(waiter_name)',
-                '  .. py:method:: sample_operation(**kwargs)',
-                '    **Request Syntax**',
-                '    ::',
-                '      response = client.sample_operation(',
-                '          Foo=\'string\'',
-                '          Bar=\'string\'',
-                '      )',
-                '    :type Foo: string',
-                '    :param Foo: Documents Foo',
-                '    :type Bar: string',
-                '    :param Bar: Documents Bar',
-                '    :rtype: dict',
-                '    :returns:',
-                '      **Response Syntax**',
-                '      ::',
-                '        {',
-                '            \'Foo\': \'string\'',
-                '            \'Bar\': \'string\'',
-                '        }',
-                '      **Response Structure**',
-                '      - *(dict) --*',
-                '        - **Foo** *(string) --*',
-                '        - **Bar** *(string) --*',
+                'These are the available methods:',
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  myservice/client/can_paginate',
+                '  myservice/client/get_paginator',
+                '  myservice/client/get_waiter',
+                '  myservice/client/sample_operation',
             ]
         )
+        self.assert_contains_lines_in_order(
+            [
+                'can_paginate',
+                '.. py:method:: can_paginate(operation_name)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'client', 'can_paginate'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'get_paginator',
+                '.. py:method:: get_paginator(operation_name)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'client', 'get_paginator'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'get_waiter',
+                '.. py:method:: get_waiter(waiter_name)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'client', 'get_waiter'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'sample_operation',
+                '.. py:method:: sample_operation(**kwargs)',
+                '  **Request Syntax**',
+                '  ::',
+                '    response = client.sample_operation(',
+                '        Foo=\'string\'',
+                '        Bar=\'string\'',
+                '    )',
+                '  :type Foo: string',
+                '  :param Foo: Documents Foo',
+                '  :type Bar: string',
+                '  :param Bar: Documents Bar',
+                '  :rtype: dict',
+                '  :returns:',
+                '    **Response Syntax**',
+                '    ::',
+                '      {',
+                '          \'Foo\': \'string\'',
+                '          \'Bar\': \'string\'',
+                '      }',
+                '    **Response Structure**',
+                '    - *(dict) --*',
+                '      - **Foo** *(string) --*',
+                '      - **Bar** *(string) --*',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'client', 'sample_operation'
+            ),
+        )
diff --git a/tests/unit/docs/test_collection.py b/tests/unit/docs/test_collection.py
index 5efb3af82e..430a475a44 100644
--- a/tests/unit/docs/test_collection.py
+++ b/tests/unit/docs/test_collection.py
@@ -16,10 +16,21 @@
 
 class TestCollectionDocumenter(BaseDocsTest):
     def test_document_collections(self):
-        collection_documenter = CollectionDocumenter(self.resource)
+        collection_documenter = CollectionDocumenter(
+            self.resource, self.root_services_path
+        )
         collection_documenter.document_collections(self.doc_structure)
         self.assert_contains_lines_in_order(
             [
+                '-----------\nCollections\n-----------',
+                'Collections provide an interface to iterate over and ',
+                'manipulate groups of resources. ',
+                'For more information about collections refer to the ',
+            ]
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'samples',
                 '.. py:attribute:: samples',
                 '  A collection of Sample resources.'
                 'A Sample Collection will include all resources by default, '
@@ -114,5 +125,8 @@ def test_document_collections(self):
                 '    :rtype: list(:py:class:`myservice.Sample`)',
                 '    :returns: A list of Sample resources',
                 '    ',
-            ]
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'samples'
+            ),
         )
diff --git a/tests/unit/docs/test_resource.py b/tests/unit/docs/test_resource.py
index 2cbb094c01..3df974e95e 100644
--- a/tests/unit/docs/test_resource.py
+++ b/tests/unit/docs/test_resource.py
@@ -18,7 +18,7 @@ class TestResourceDocumenter(BaseDocsTest):
     def test_document_resource(self):
         resource = self.resource.Sample('mysample')
         resource_documenter = ResourceDocumenter(
-            resource, self.botocore_session
+            resource, self.botocore_session, self.root_services_path
         )
         resource_documenter.document_resource(self.doc_structure)
         self.assert_contains_lines_in_order(
@@ -26,47 +26,80 @@ def test_document_resource(self):
                 '======',
                 'Sample',
                 '======',
+                'Before using anything on this page, please refer to the resources ',
+                ':doc:`user guide <../../../../guide/resources>` for the most recent ',
+                'guidance on using resources.',
                 '.. py:class:: MyService.Sample(name)',
                 '  A resource representing an AWS MyService Sample::',
                 '    import boto3',
                 "    myservice = boto3.resource('myservice')",
                 "    sample = myservice.Sample('name')",
-                "  These are the resource's available identifiers:",
-                '  *   :py:attr:`name`',
-                "  These are the resource's available attributes:",
-                '  *   :py:attr:`bar`',
-                '  *   :py:attr:`foo`',
-                "  These are the resource's available actions:",
-                '  *   :py:meth:`load()`',
-                '  *   :py:meth:`operate()`',
-                '  *   :py:meth:`reload()`',
-                "  These are the resource's available waiters:",
-                '  *   :py:meth:`wait_until_complete()`',
-                '  .. rst-class:: admonition-title',
-                '  Identifiers',
-                '  .. py:attribute:: name',
-                '  .. rst-class:: admonition-title',
-                '  Attributes',
-                '  .. py:attribute:: bar',
-                '    - *(string) --* Documents Bar',
-                '  .. py:attribute:: foo',
-                '    - *(string) --* Documents Foo',
-                '  .. rst-class:: admonition-title',
-                '  Actions',
-                '  .. py:method:: load()',
-                '  .. py:method:: operate(**kwargs)',
-                '  .. py:method:: reload()',
-                '  .. rst-class:: admonition-title',
-                '  Waiters',
-                '  .. py:method:: wait_until_complete(**kwargs)',
+                'Identifiers',
+                "These are the resource's available identifiers:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  name',
+                'Attributes',
+                "These are the resource's available attributes:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  bar',
+                '  foo',
+                'Actions',
+                "These are the resource's available actions:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  load',
+                '  operate',
+                '  reload',
+                'Waiters',
+                "These are the resource's available waiters:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  wait_until_complete',
             ]
         )
+        self.assert_contains_lines_in_order(
+            [
+                'name',
+                '.. py:attribute:: name',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'name'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'bar',
+                '.. py:attribute:: bar',
+                '  - *(string) --* Documents Bar',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'bar'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'load',
+                '.. py:method:: load()',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'load'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'wait_until_complete',
+                '.. py:method:: wait_until_complete(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'sample', 'wait_until_complete'
+            ),
+        )
 
 
 class TestServiceResourceDocumenter(BaseDocsTest):
     def test_document_resource(self):
         resource_documenter = ServiceResourceDocumenter(
-            self.resource, self.botocore_session
+            self.resource, self.botocore_session, self.root_services_path
         )
         resource_documenter.document_resource(self.doc_structure)
         self.assert_contains_lines_in_order(
@@ -74,28 +107,61 @@ def test_document_resource(self):
                 '================',
                 'Service Resource',
                 '================',
+                'Before using anything on this page, please refer to the resources ',
+                ':doc:`user guide <../../../../guide/resources>` for the most recent ',
+                'guidance on using resources.',
                 '.. py:class:: MyService.ServiceResource()',
                 '  A resource representing AWS MyService::',
                 '    import boto3',
                 "    myservice = boto3.resource('myservice')",
-                "  These are the resource's available actions:",
-                '  *   :py:meth:`sample_operation()`',
-                "  These are the resource's available sub-resources:",
-                '  *   :py:meth:`Sample()`',
-                "  These are the resource's available collections:",
-                '  *   :py:attr:`samples`',
-                '  .. rst-class:: admonition-title',
-                '  Actions',
-                '  .. py:method:: sample_operation(**kwargs)',
-                '  .. rst-class:: admonition-title',
-                '  Sub-resources',
-                '  .. py:method:: Sample(name)',
-                '  .. rst-class:: admonition-title',
-                '  Collections',
-                '  .. py:attribute:: samples',
-                '    .. py:method:: all()',
-                '    .. py:method:: filter(**kwargs)',
-                '    .. py:method:: limit(**kwargs)',
-                '    .. py:method:: page_size(**kwargs)',
+                'Actions',
+                "These are the resource's available actions:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  sample_operation',
+                'Sub-resources',
+                "These are the resource's available sub-resources:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  Sample',
+                'Collections',
+                "These are the resource's available collections:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  samples',
             ]
         )
+        self.assert_contains_lines_in_order(
+            [
+                'sample_operation',
+                '.. py:method:: sample_operation(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'sample_operation'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'Sample',
+                '.. py:method:: Sample(name)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'Sample'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'samples',
+                '.. py:attribute:: samples',
+                '  .. py:method:: all()',
+                '  .. py:method:: filter(**kwargs)',
+                '  .. py:method:: limit(**kwargs)',
+                '  .. py:method:: page_size(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'samples'
+            ),
+        )
diff --git a/tests/unit/docs/test_service.py b/tests/unit/docs/test_service.py
index 7977b375e0..d67904b439 100644
--- a/tests/unit/docs/test_service.py
+++ b/tests/unit/docs/test_service.py
@@ -20,7 +20,9 @@
 
 class TestServiceDocumenter(BaseDocsTest):
     def test_document_service(self):
-        service_documenter = ServiceDocumenter('myservice', self.session)
+        service_documenter = ServiceDocumenter(
+            'myservice', self.session, self.root_services_path
+        )
         contents = service_documenter.document_service().decode('utf-8')
         lines = [
             '*********',
@@ -32,71 +34,201 @@ def test_document_service(self):
             'Client',
             '======',
             '.. py:class:: MyService.Client',
-            '  These are the available methods:',
-            '  *   :py:meth:`~MyService.Client.sample_operation`',
-            '    **Examples** ',
-            '    Sample Description.',
-            '    ::',
-            '      response = client.sample_operation(',
+            'These are the available methods:',
+            '  myservice/client/sample_operation',
             '==========',
             'Paginators',
             '==========',
             'The available paginators are:',
-            '* :py:class:`MyService.Paginator.SampleOperation`',
-            '.. py:class:: MyService.Paginator.SampleOperation',
-            '  .. py:method:: paginate(**kwargs)',
+            '  myservice/paginator/SampleOperation',
             '=======',
             'Waiters',
             '=======',
             'The available waiters are:',
-            '* :py:class:`MyService.Waiter.SampleOperationComplete`',
-            '.. py:class:: MyService.Waiter.SampleOperationComplete',
-            '  .. py:method:: wait(**kwargs)',
-            '================',
-            'Service Resource',
-            '================',
-            '.. py:class:: MyService.ServiceResource()',
-            "  These are the resource's available actions:",
-            '  *   :py:meth:`sample_operation()`',
-            "  These are the resource's available sub-resources:",
-            '  *   :py:meth:`Sample()`',
-            "  These are the resource's available collections:",
-            '  *   :py:attr:`samples`',
-            '  .. py:method:: sample_operation(**kwargs)',
-            '  .. py:method:: Sample(name)',
-            '  .. py:attribute:: samples',
-            '    .. py:method:: all()',
-            '    .. py:method:: filter(**kwargs)',
-            '    .. py:method:: limit(**kwargs)',
-            '    .. py:method:: page_size(**kwargs)',
-            '======',
-            'Sample',
-            '======',
-            '.. py:class:: MyService.Sample(name)',
-            "  These are the resource's available identifiers:",
-            '  *   :py:attr:`name`',
-            "  These are the resource's available attributes:",
-            '  *   :py:attr:`bar`',
-            '  *   :py:attr:`foo`',
-            "  These are the resource's available actions:",
-            '  *   :py:meth:`load()`',
-            '  *   :py:meth:`operate()`',
-            '  *   :py:meth:`reload()`',
-            "  These are the resource's available waiters:",
-            '  *   :py:meth:`wait_until_complete()`',
-            '  .. py:attribute:: name',
-            '  .. py:attribute:: bar',
-            '  .. py:attribute:: foo',
-            '  .. py:method:: load()',
-            '  .. py:method:: operate(**kwargs)',
-            '  .. py:method:: reload()',
-            '  .. py:method:: wait_until_complete(**kwargs)',
+            '  myservice/waiter/SampleOperationComplete',
+            '=========',
+            'Resources',
+            '=========',
+            'Resources are available in boto3 via the ',
+            '``resource`` method. For more detailed instructions ',
+            'and examples on the usage of resources, see the ',
+            'resources ',
+            'The available resources are:',
+            '  myservice/service-resource/index',
+            '  myservice/sample/index',
         ]
         self.assert_contains_lines_in_order(lines, contents)
+        self.assert_contains_lines_in_order(
+            [
+                '================',
+                'Service Resource',
+                '================',
+                '.. py:class:: MyService.ServiceResource()',
+                '  A resource representing AWS MyService::',
+                '    import boto3',
+                "    myservice = boto3.resource('myservice')",
+                'Actions',
+                "These are the resource's available actions:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  sample_operation',
+                'Sub-resources',
+                "These are the resource's available sub-resources:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  Sample',
+                'Collections',
+                "These are the resource's available collections:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  samples',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'index'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                '======',
+                'Sample',
+                '======',
+                '.. py:class:: MyService.Sample(name)',
+                "These are the resource's available identifiers:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  name',
+                "These are the resource's available attributes:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  bar',
+                '  foo',
+                "These are the resource's available actions:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  load',
+                '  operate',
+                '  reload',
+                "These are the resource's available waiters:",
+                '.. toctree::',
+                '  :maxdepth: 1',
+                '  :titlesonly:',
+                '  wait_until_complete',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'index'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'sample_operation',
+                '.. py:method:: sample_operation(**kwargs)',
+                '  **Examples** ',
+                '  Sample Description.',
+                '  ::',
+                '    response = client.sample_operation(',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'client', 'sample_operation'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'SampleOperation',
+                '.. py:class:: MyService.Paginator.SampleOperation',
+                '  .. py:method:: paginate(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'paginator', 'SampleOperation'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'SampleOperationComplete',
+                '.. py:class:: MyService.Waiter.SampleOperationComplete',
+                '  .. py:method:: wait(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'waiter', 'SampleOperationComplete'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'sample_operation',
+                '.. py:method:: sample_operation(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'sample_operation'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'Sample',
+                '.. py:method:: Sample(name)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'Sample'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'samples',
+                '.. py:attribute:: samples',
+                '  .. py:method:: all()',
+                '  .. py:method:: filter(**kwargs)',
+                '  .. py:method:: limit(**kwargs)',
+                '  .. py:method:: page_size(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'samples'
+            ),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'name',
+                '.. py:attribute:: name',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'name'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'name',
+                '.. py:attribute:: name',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'name'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'bar',
+                '.. py:attribute:: bar',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'bar'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'load',
+                '.. py:method:: load()',
+            ],
+            self.get_nested_service_contents('myservice', 'sample', 'load'),
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'wait_until_complete',
+                '.. py:method:: wait_until_complete(**kwargs)',
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'sample', 'wait_until_complete'
+            ),
+        )
 
     def test_document_service_no_resource(self):
         os.remove(self.resource_model_file)
-        service_documenter = ServiceDocumenter('myservice', self.session)
+        service_documenter = ServiceDocumenter(
+            'myservice', self.session, self.root_services_path
+        )
         contents = service_documenter.document_service().decode('utf-8')
         assert 'Service Resource' not in contents
 
@@ -105,7 +237,9 @@ def test_document_service_no_paginators(self):
         # as it may try to look at the paginator model during documentation.
         os.remove(self.resource_model_file)
         os.remove(self.paginator_model_file)
-        service_documenter = ServiceDocumenter('myservice', self.session)
+        service_documenter = ServiceDocumenter(
+            'myservice', self.session, self.root_services_path
+        )
         contents = service_documenter.document_service().decode('utf-8')
         assert 'Paginators' not in contents
 
@@ -114,7 +248,9 @@ def test_document_service_no_waiter(self):
         # as it may try to look at the waiter model during documentation.
         os.remove(self.resource_model_file)
         os.remove(self.waiter_model_file)
-        service_documenter = ServiceDocumenter('myservice', self.session)
+        service_documenter = ServiceDocumenter(
+            'myservice', self.session, self.root_services_path
+        )
         contents = service_documenter.document_service().decode('utf-8')
         assert 'Waiters' not in contents
 
@@ -125,7 +261,9 @@ def test_creates_correct_path_to_examples_based_on_service_name(self):
         path = os.path.realpath(path)
         with mock.patch('os.path.isfile') as isfile:
             isfile.return_value = False
-            s = ServiceDocumenter('myservice', self.session)
+            s = ServiceDocumenter(
+                'myservice', self.session, self.root_services_path
+            )
             s.document_service()
             assert isfile.call_args_list[-1] == mock.call(path)
 
@@ -133,7 +271,9 @@ def test_injects_examples_when_found(self):
         examples_path = os.sep.join(
             [os.path.dirname(__file__), '..', 'data', 'examples']
         )
-        service_documenter = ServiceDocumenter('myservice', self.session)
+        service_documenter = ServiceDocumenter(
+            'myservice', self.session, self.root_services_path
+        )
         service_documenter.EXAMPLE_PATH = examples_path
         contents = service_documenter.document_service().decode('utf-8')
         assert 'This is an example' in contents
diff --git a/tests/unit/docs/test_subresource.py b/tests/unit/docs/test_subresource.py
index e5a1a72c59..4e31cd538e 100644
--- a/tests/unit/docs/test_subresource.py
+++ b/tests/unit/docs/test_subresource.py
@@ -16,10 +16,22 @@
 
 class TestSubResourceDocumenter(BaseDocsTest):
     def test_document_sub_resources(self):
-        sub_resource_documentor = SubResourceDocumenter(self.resource)
+        sub_resource_documentor = SubResourceDocumenter(
+            self.resource, self.root_services_path
+        )
         sub_resource_documentor.document_sub_resources(self.doc_structure)
         self.assert_contains_lines_in_order(
             [
+                '-------------\nSub-resources\n-------------',
+                'Sub-resources are methods that create a new instance of a',
+                ' child resource. This resource\'s identifiers get passed',
+                ' along to the child.',
+                'For more information about sub-resources refer to the ',
+            ]
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'Sample',
                 '.. py:method:: Sample(name)',
                 '  Creates a Sample resource.::',
                 "    sample = myservice.Sample('name')",
@@ -27,5 +39,8 @@ def test_document_sub_resources(self):
                 "  :param name: The Sample's name identifier.",
                 '  :rtype: :py:class:`MyService.Sample`',
                 '  :returns: A Sample resource',
-            ]
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'service-resource', 'Sample'
+            ),
         )
diff --git a/tests/unit/docs/test_waiter.py b/tests/unit/docs/test_waiter.py
index d1cb57f4a7..9a4ff48825 100644
--- a/tests/unit/docs/test_waiter.py
+++ b/tests/unit/docs/test_waiter.py
@@ -21,11 +21,20 @@ def test_document_resource_waiters(self):
         )
         subresource = self.resource.Sample('mysample')
         waiter_documenter = WaiterResourceDocumenter(
-            subresource, service_waiter_model
+            subresource, service_waiter_model, self.root_services_path
         )
         waiter_documenter.document_resource_waiters(self.doc_structure)
         self.assert_contains_lines_in_order(
             [
+                '-------\nWaiters\n-------',
+                'Waiters provide an interface to wait for a resource',
+                ' to reach a specific state.',
+                'For more information about waiters refer to the',
+            ]
+        )
+        self.assert_contains_lines_in_order(
+            [
+                'wait_until_complete',
                 '.. py:method:: wait_until_complete(**kwargs)',
                 (
                     '  Waits until this Sample is complete. This method calls '
@@ -42,5 +51,8 @@ def test_document_resource_waiters(self):
                 '  :type Bar: string',
                 '  :param Bar: Documents Bar',
                 '  :returns: None',
-            ]
+            ],
+            self.get_nested_service_contents(
+                'myservice', 'sample', 'wait_until_complete'
+            ),
         )