1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
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: <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,
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()
|
