1# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.
2#
3# Licensed under the Apache License, Version 2.0 (the "License"). You
4# may not use this file except in compliance with the License. A copy of
5# the License is located at
6#
7# http://aws.amazon.com/apache2.0/
8#
9# or in the "license" file accompanying this file. This file is
10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF
11# ANY KIND, either express or implied. See the License for the specific
12# language governing permissions and limitations under the License.
13from botocore.docs.params import ResponseParamsDocumenter
14
15from boto3.docs.utils import get_identifier_description
16
17
18class ResourceShapeDocumenter(ResponseParamsDocumenter):
19    EVENT_NAME = 'resource-shape'
20
21
22def document_attribute(section, service_name, resource_name, attr_name,
23                       event_emitter, attr_model, include_signature=True):
24    if include_signature:
25        section.style.start_sphinx_py_attr(attr_name)
26    # Note that an attribute may have one, may have many, or may have no
27    # operations that back the resource's shape. So we just set the
28    # operation_name to the resource name if we ever to hook in and modify
29    # a particular attribute.
30    ResourceShapeDocumenter(
31        service_name=service_name, operation_name=resource_name,
32        event_emitter=event_emitter).document_params(
33            section=section,
34            shape=attr_model)
35
36
37def document_identifier(section, resource_name, identifier_model,
38                        include_signature=True):
39    if include_signature:
40        section.style.start_sphinx_py_attr(identifier_model.name)
41    description = get_identifier_description(
42        resource_name, identifier_model.name)
43    description = '*(string)* ' + description
44    section.write(description)
45
46
47def document_reference(section, reference_model, include_signature=True):
48    if include_signature:
49        section.style.start_sphinx_py_attr(reference_model.name)
50    reference_type = '(:py:class:`%s`) ' % reference_model.resource.type
51    section.write(reference_type)
52    section.include_doc_string(
53        'The related %s if set, otherwise ``None``.' % reference_model.name
54    )
55