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
|
# 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
#
# http://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.
from botocore.docs.bcdoc.restdoc import DocumentStructure
from botocore.docs.client import (
ClientContextParamsDocumenter,
ClientDocumenter,
ClientExceptionsDocumenter,
)
from botocore.docs.paginator import PaginatorDocumenter
from botocore.docs.waiter import WaiterDocumenter
from botocore.exceptions import DataNotFoundError
class ServiceDocumenter:
def __init__(self, service_name, session, root_docs_path):
self._session = session
self._service_name = service_name
self._root_docs_path = root_docs_path
self._client = self._session.create_client(
service_name,
region_name='us-east-1',
aws_access_key_id='foo',
aws_secret_access_key='bar',
)
self._event_emitter = self._client.meta.events
self.sections = [
'title',
'client-api',
'client-exceptions',
'paginator-api',
'waiter-api',
'client-context-params',
]
def document_service(self):
"""Documents an entire service.
:returns: The reStructured text of the documented service.
"""
doc_structure = DocumentStructure(
self._service_name, section_names=self.sections, target='html'
)
self.title(doc_structure.get_section('title'))
self.client_api(doc_structure.get_section('client-api'))
self.client_exceptions(doc_structure.get_section('client-exceptions'))
self.paginator_api(doc_structure.get_section('paginator-api'))
self.waiter_api(doc_structure.get_section('waiter-api'))
context_params_section = doc_structure.get_section(
'client-context-params'
)
self.client_context_params(context_params_section)
return doc_structure.flush_structure()
def title(self, section):
section.style.h1(self._client.__class__.__name__)
self._event_emitter.emit(
f"docs.title.{self._service_name}", section=section
)
def table_of_contents(self, section):
section.style.table_of_contents(title='Table of Contents', depth=2)
def client_api(self, section):
examples = None
try:
examples = self.get_examples(self._service_name)
except DataNotFoundError:
pass
ClientDocumenter(
self._client, self._root_docs_path, examples
).document_client(section)
def client_exceptions(self, section):
ClientExceptionsDocumenter(
self._client, self._root_docs_path
).document_exceptions(section)
def paginator_api(self, section):
try:
service_paginator_model = self._session.get_paginator_model(
self._service_name
)
except DataNotFoundError:
return
if service_paginator_model._paginator_config:
paginator_documenter = PaginatorDocumenter(
self._client, service_paginator_model, self._root_docs_path
)
paginator_documenter.document_paginators(section)
def waiter_api(self, section):
if self._client.waiter_names:
service_waiter_model = self._session.get_waiter_model(
self._service_name
)
waiter_documenter = WaiterDocumenter(
self._client, service_waiter_model, self._root_docs_path
)
waiter_documenter.document_waiters(section)
def get_examples(self, service_name, api_version=None):
loader = self._session.get_component('data_loader')
examples = loader.load_service_model(
service_name, 'examples-1', api_version
)
return examples['examples']
def client_context_params(self, section):
omitted_params = ClientContextParamsDocumenter.OMITTED_CONTEXT_PARAMS
params_to_omit = omitted_params.get(self._service_name, [])
service_model = self._client.meta.service_model
raw_context_params = service_model.client_context_parameters
context_params = [
p for p in raw_context_params if p.name not in params_to_omit
]
if context_params:
context_param_documenter = ClientContextParamsDocumenter(
self._service_name, context_params
)
context_param_documenter.document_context_params(section)
|
