codekingpro/portable-devtools

1# Copyright 2015 Amazon.com, Inc. or its affiliates. All Rights Reserved.2#3# Licensed under the Apache License, Version 2.0 (the "License"). You4# may not use this file except in compliance with the License. A copy of5# the License is located at6#7# http://aws.amazon.com/apache2.0/8#9# or in the "license" file accompanying this file. This file is10# distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF11# ANY KIND, either express or implied. See the License for the specific12# language governing permissions and limitations under the License.13from botocore.docs.bcdoc.restdoc import DocumentStructure14from botocore.docs.client import (15    ClientContextParamsDocumenter,16    ClientDocumenter,17    ClientExceptionsDocumenter,18)19from botocore.docs.paginator import PaginatorDocumenter20from botocore.docs.waiter import WaiterDocumenter21from botocore.exceptions import DataNotFoundError22 23 24class ServiceDocumenter:25    def __init__(self, service_name, session, root_docs_path):26        self._session = session27        self._service_name = service_name28        self._root_docs_path = root_docs_path29 30        self._client = self._session.create_client(31            service_name,32            region_name='us-east-1',33            aws_access_key_id='foo',34            aws_secret_access_key='bar',35        )36        self._event_emitter = self._client.meta.events37 38        self.sections = [39            'title',40            'client-api',41            'client-exceptions',42            'paginator-api',43            'waiter-api',44            'client-context-params',45        ]46 47    def document_service(self):48        """Documents an entire service.49 50        :returns: The reStructured text of the documented service.51        """52        doc_structure = DocumentStructure(53            self._service_name, section_names=self.sections, target='html'54        )55        self.title(doc_structure.get_section('title'))56        self.client_api(doc_structure.get_section('client-api'))57        self.client_exceptions(doc_structure.get_section('client-exceptions'))58        self.paginator_api(doc_structure.get_section('paginator-api'))59        self.waiter_api(doc_structure.get_section('waiter-api'))60        context_params_section = doc_structure.get_section(61            'client-context-params'62        )63        self.client_context_params(context_params_section)64        return doc_structure.flush_structure()65 66    def title(self, section):67        section.style.h1(self._client.__class__.__name__)68        self._event_emitter.emit(69            f"docs.title.{self._service_name}", section=section70        )71 72    def table_of_contents(self, section):73        section.style.table_of_contents(title='Table of Contents', depth=2)74 75    def client_api(self, section):76        examples = None77        try:78            examples = self.get_examples(self._service_name)79        except DataNotFoundError:80            pass81 82        ClientDocumenter(83            self._client, self._root_docs_path, examples84        ).document_client(section)85 86    def client_exceptions(self, section):87        ClientExceptionsDocumenter(88            self._client, self._root_docs_path89        ).document_exceptions(section)90 91    def paginator_api(self, section):92        try:93            service_paginator_model = self._session.get_paginator_model(94                self._service_name95            )96        except DataNotFoundError:97            return98        if service_paginator_model._paginator_config:99            paginator_documenter = PaginatorDocumenter(100                self._client, service_paginator_model, self._root_docs_path101            )102            paginator_documenter.document_paginators(section)103 104    def waiter_api(self, section):105        if self._client.waiter_names:106            service_waiter_model = self._session.get_waiter_model(107                self._service_name108            )109            waiter_documenter = WaiterDocumenter(110                self._client, service_waiter_model, self._root_docs_path111            )112            waiter_documenter.document_waiters(section)113 114    def get_examples(self, service_name, api_version=None):115        loader = self._session.get_component('data_loader')116        examples = loader.load_service_model(117            service_name, 'examples-1', api_version118        )119        return examples['examples']120 121    def client_context_params(self, section):122        omitted_params = ClientContextParamsDocumenter.OMITTED_CONTEXT_PARAMS123        params_to_omit = omitted_params.get(self._service_name, [])124        service_model = self._client.meta.service_model125        raw_context_params = service_model.client_context_parameters126        context_params = [127            p for p in raw_context_params if p.name not in params_to_omit128        ]129        if context_params:130            context_param_documenter = ClientContextParamsDocumenter(131                self._service_name, context_params132            )133            context_param_documenter.document_context_params(section)134