From 4a52a71956a8d46fcb7294ac71734504bb09bcc2 Mon Sep 17 00:00:00 2001 From: S. Solomon Darnell Date: Fri, 28 Mar 2025 21:52:21 -0500 Subject: two version of R2R are here --- .../site-packages/boto3/docs/subresource.py | 145 +++++++++++++++++++++ 1 file changed, 145 insertions(+) create mode 100644 .venv/lib/python3.12/site-packages/boto3/docs/subresource.py (limited to '.venv/lib/python3.12/site-packages/boto3/docs/subresource.py') diff --git a/.venv/lib/python3.12/site-packages/boto3/docs/subresource.py b/.venv/lib/python3.12/site-packages/boto3/docs/subresource.py new file mode 100644 index 00000000..a28203d4 --- /dev/null +++ b/.venv/lib/python3.12/site-packages/boto3/docs/subresource.py @@ -0,0 +1,145 @@ +# Copyright 2015 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. A copy of +# the License is located at +# +# https://aws.amazon.com/apache2.0/ +# +# or in the "license" file accompanying this file. This file 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. +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 NestedDocumenter +from boto3.docs.utils import ( + add_resource_type_overview, + get_identifier_args_for_signature, + get_identifier_description, + get_identifier_values_for_example, +) + + +class SubResourceDocumenter(NestedDocumenter): + def document_sub_resources(self, section): + add_resource_type_overview( + section=section, + resource_type='Sub-resources', + description=( + 'Sub-resources are methods that create a new instance of a' + ' child resource. This resource\'s identifiers get passed' + ' along to the child.' + ), + intro_link='subresources_intro', + ) + sub_resources = sorted( + self._resource.meta.resource_model.subresources, + key=lambda sub_resource: sub_resource.name, + ) + sub_resources_list = [] + self.member_map['sub-resources'] = sub_resources_list + for sub_resource in sub_resources: + 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' + ) + breadcrumb_section = sub_resource_doc.add_new_section('breadcrumb') + breadcrumb_section.style.ref(self._resource_class_name, 'index') + breadcrumb_section.write(f' / Sub-Resource / {sub_resource.name}') + sub_resource_doc.add_title_section(sub_resource.name) + sub_resource_section = sub_resource_doc.add_new_section( + sub_resource.name, + context={'qualifier': f'{self.class_name}.'}, + ) + document_sub_resource( + section=sub_resource_section, + resource_name=self._resource_name, + sub_resource_model=sub_resource, + service_model=self._service_model, + ) + + # Write sub_resources in individual/nested files. + # Path: /reference/services///.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, + resource_name, + sub_resource_model, + service_model, + include_signature=True, +): + """Documents a resource action + + :param section: The section to write to + + :param resource_name: The name of the resource + + :param sub_resource_model: The model of the subresource + + :param service_model: The model of the service + + :param include_signature: Whether or not to include the signature. + It is useful for generating docstrings. + """ + identifiers_needed = [] + for identifier in sub_resource_model.resource.identifiers: + if identifier.source == 'input': + identifiers_needed.append(xform_name(identifier.target)) + + if include_signature: + signature_args = get_identifier_args_for_signature(identifiers_needed) + full_sub_resource_name = ( + f"{section.context.get('qualifier', '')}{sub_resource_model.name}" + ) + section.style.start_sphinx_py_method( + full_sub_resource_name, signature_args + ) + + method_intro_section = section.add_new_section('method-intro') + description = f'Creates a {sub_resource_model.resource.type} resource.' + method_intro_section.include_doc_string(description) + example_section = section.add_new_section('example') + example_values = get_identifier_values_for_example(identifiers_needed) + example_resource_name = xform_name(resource_name) + if service_model.service_name == resource_name: + example_resource_name = resource_name + example = f'{xform_name(sub_resource_model.resource.type)} = {example_resource_name}.{sub_resource_model.name}({example_values})' + example_section.style.start_codeblock() + example_section.write(example) + example_section.style.end_codeblock() + + param_section = section.add_new_section('params') + for identifier in identifiers_needed: + description = get_identifier_description( + sub_resource_model.name, identifier + ) + param_section.write(f':type {identifier}: string') + param_section.style.new_line() + param_section.write(f':param {identifier}: {description}') + param_section.style.new_line() + + return_section = section.add_new_section('return') + return_section.style.new_line() + return_section.write( + f':rtype: :py:class:`{get_service_module_name(service_model)}.{sub_resource_model.resource.type}`' + ) + return_section.style.new_line() + return_section.write( + f':returns: A {sub_resource_model.resource.type} resource' + ) + return_section.style.new_line() -- cgit v1.2.3