aws-sdk-core 2.0.48 → 2.1.0

data/lib/aws-sdk-core/api/docs/builder.rb

@@ -0,0 +1,220 @@
+require 'erb'
+
+module Aws
+  module Api
+    module Docs
+      class Builder
+
+        def self.document(svc_module)
+          new(svc_module).document
+        end
+
+        def initialize(svc_module)
+          @svc_module = svc_module
+          @svc_name = svc_module.name.split('::').last
+          @client_class = svc_module.const_get(:Client)
+          @api = @client_class.api
+          @full_name = @api.metadata['serviceFullName']
+          @error_names = @api.operations.map {|_,o| o.errors.map(&:shape).map(&:name) }
+          @error_names = @error_names.flatten.uniq.sort
+          @namespace = YARD::Registry['Aws']
+        end
+
+        def document
+          document_service
+          document_types
+          document_client
+          document_errors
+        end
+
+        private
+
+        def document_service
+          yard_mod = YARD::CodeObjects::ModuleObject.new(@namespace, @svc_name)
+          yard_mod.docstring = service_docstring
+          yard_mod.docstring.add_tag(YARD::Tags::Tag.new(:service, @svc_name))
+          @namespace = yard_mod
+        end
+
+        def service_docstring
+          path = "doc-src/services/#{@svc_name}/service.md"
+          path = 'doc-src/services/default/service.md' unless File.exists?(path)
+          template = read(path)
+          svc_name = @svc_name
+          api = @api
+          full_name = @full_name
+          ERB.new(template).result(binding)
+        end
+
+        def document_errors
+          yard_mod = YARD::CodeObjects::ModuleObject.new(@namespace, 'Errors')
+          yard_mod.docstring = errors_docstring
+
+          base_error = YARD::CodeObjects::ClassObject.new(yard_mod, 'ServiceError')
+          base_error.docstring = "Base class for all Aws::#{@svc_name} errors."
+          base_error.superclass = YARD::Registry['Aws::Errors::ServiceError']
+
+          @error_names.each do |error_name|
+            error_klass = YARD::CodeObjects::ClassObject.new(yard_mod, error_name)
+            error_klass.superclass = base_error
+          end
+        end
+
+        def errors_docstring
+          path = "doc-src/services/#{@svc_name}/errors.md"
+          path = 'doc-src/services/default/errors.md' unless File.exists?(path)
+          template = read(path)
+          svc_name = @svc_name
+          api = @api
+          full_name = @full_name
+          known_errors = @error_names
+          ERB.new(template).result(binding)
+        end
+
+        def document_client
+          yard_class = YARD::CodeObjects::ClassObject.new(@namespace, 'Client')
+          yard_class.superclass = YARD::Registry['Seahorse::Client::Base']
+          yard_class.docstring = client_docstring
+          document_client_constructor(yard_class)
+          document_client_operations(yard_class)
+          document_client_waiters(yard_class)
+        end
+
+        def document_types
+          namespace = YARD::CodeObjects::ModuleObject.new(@namespace, 'Types')
+          documenter = ClientTypeDocumenter.new(namespace)
+          @api.metadata['shapes'].each_structure do |shape|
+            documenter.document(@api, shape)
+          end
+        end
+
+        def client_docstring
+          path = "doc-src/services/#{@svc_name}/client.md"
+          path = 'doc-src/services/default/client.md' unless File.exists?(path)
+          render(path)
+        end
+
+        def render(path)
+          svc_name = @svc_name
+          api = @api
+          full_name = @full_name
+          ERB.new(File.read(path)).result(binding)
+        end
+
+        def document_client_constructor(namespace)
+          constructor = YARD::CodeObjects::MethodObject.new(namespace, :initialize)
+          constructor.group = 'Constructor'
+          constructor.scope = :instance
+          constructor.parameters << ['options', '{}']
+          constructor.docstring = client_constructor_docstring
+        end
+
+        def client_constructor_docstring
+          <<-DOCS.strip
+  Constructs an API client.
+  #{client_constructor_options}
+  @return [#{@client_class.name}] Returns an API client.
+          DOCS
+        end
+
+        def client_constructor_options
+          options = {}
+          @client_class.plugins.each do |plugin|
+            if p = YARD::Registry[plugin.name]
+              p.tags.each do |tag|
+                if tag.tag_name == 'seahorse_client_option'
+                  option_name = tag.text.match(/.+(:\w+)/)[1]
+                  option_text = "@option options " + tag.text.split("\n").join("\n  ")
+                  options[option_name] = option_text +
+                    "  See {#{plugin.name}} for more details."
+                end
+              end
+            end
+          end
+          options.sort_by { |k,v| k }.map(&:last).join("\n")
+        end
+
+        def document_client_operations(namespace)
+          @api.operations.each do |method_name, operation|
+            document_client_operation(namespace, method_name, operation)
+          end
+        end
+
+        def document_client_operation(namespace, method_name, operation)
+          documenter = OperationDocumenter.new(@svc_name, namespace)
+          documenter.document(method_name, operation)
+        end
+
+        def document_client_waiters(yard_class)
+          m = YARD::CodeObjects::MethodObject.new(yard_class, :wait_until)
+          m.scope = :instance
+          m.parameters << ['waiter_name', nil]
+          m.parameters << ['params', '{}']
+          m.docstring = YARD::Registry['Aws::ClientWaiters#wait_until'].docstring
+
+          waiters = @client_class.waiters.waiter_names.sort.inject('') do |w,name|
+            waiter = @client_class.waiters.waiter(name)
+            operation = waiter.poller.operation_name
+            w << "<tr><td><tt>:#{name}</tt></td><td>{##{operation}}</td><td>#{waiter.delay}</td><td>#{waiter.max_attempts}</td></tr>"
+          end
+          docstring = <<-DOCSTRING
+  Returns the list of supported waiters. The following table lists the supported
+  waiters and the client method they call:
+  <table>
+  <thead>
+  <tr><th>Waiter Name</th><th>Client Method</th><th>Delay</th><th>Max Attempts</th></tr>
+  </thead>
+  <tbody>
+  #{waiters}
+  </tbody>
+  </table>
+  @return [Array<Symbol>] the list of supported waiters.
+          DOCSTRING
+          m = YARD::CodeObjects::MethodObject.new(yard_class, :waiter_names)
+          m.scope = :instance
+          m.docstring = docstring
+        end
+
+        class Tabulator
+
+          def initialize
+            @tabs = []
+            @tab_contents = []
+          end
+
+          def tab(method_name, tab_name, &block)
+            tab_class = tab_name.downcase.gsub(/[^a-z]+/i, '-')
+            tab_id = "#{method_name.to_s.gsub(/_/, '-')}-#{tab_class}"
+            class_names = ['tab-contents', tab_class]
+            @tabs << [tab_id, tab_name]
+            @tab_contents << "<div class=\"#{class_names.join(' ')}\" id=\"#{tab_id}\">"
+            @tab_contents << yield
+            @tab_contents << '</div>'
+          end
+
+          def to_html
+            lines = []
+            lines << '<div class="tab-box">'
+            lines << '<ul class="tabs">'
+            @tabs.each do |tab_id, tab_name|
+              lines << "<li data-tab-id=\"#{tab_id}\">#{tab_name}</li>"
+            end
+            lines << '</ul>'
+            lines.concat(@tab_contents)
+            lines << '</div>'
+            lines.join
+          end
+          alias inspect to_html
+          alias to_str to_html
+          alias to_s to_html
+
+        end
+
+        def read(path)
+          File.open(path, 'r', encoding: 'UTF-8') { |f| f.read }
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/docs/client_type_documenter.rb

@@ -0,0 +1,109 @@
+module Aws
+  module Api
+    module Docs
+      class ClientTypeDocumenter
+
+        include Utils
+        include Seahorse::Model
+        include Seahorse::Model::Shapes
+
+        # @param [Yard::CodeObjects::Base] namespace
+        def initialize(namespace)
+          @namespace = namespace
+        end
+
+        # @param [Seahorse::Model::Api] api
+        # @param [Seahorse::Model::Shapes::StructureShape] shape
+        def document(api, shape)
+          yard_class = YARD::CodeObjects::ClassObject.new(@namespace, shape.name)
+          yard_class.superclass = 'Struct'
+          yard_class.docstring = docstring(api, shape)
+          tags(api, shape).each do |tag|
+            yard_class.add_tag(tag)
+          end
+          shape.members.each do |member_name, ref|
+            document_struct_member(yard_class, member_name, ref)
+          end
+        end
+
+        private
+
+        def docstring(api, shape)
+          docs = shape.documentation || ''
+          methods = returned_by(api, shape)
+          unless methods.empty?
+            docs += "<p>Returned by:</p>"
+            docs += "<ul>"
+            docs += methods.map{|m| "<li>{#{m}}</li>" }.join
+            docs += "</ul>"
+          end
+          docs
+        end
+
+        def tags(api, shape)
+          tags = []
+          tags << input_example_tag(api, shape) if input_shape?(api, shape)
+          tags
+        end
+
+        # Returns `true` if the given shape is ever used as input in the api.
+        def input_shape?(haystack, needle, stack = [])
+          if stack.include?(haystack)
+            return false
+          else
+            stack += [haystack]
+          end
+          case haystack
+          when needle
+            return true
+          when Seahorse::Model::Api
+            haystack.operations.each do |_, operation|
+              if operation.input && input_shape?(operation.input.shape, needle, stack)
+                return true
+              end
+            end
+          when StructureShape
+            haystack.members.each do |_, member_ref|
+              if input_shape?(member_ref.shape, needle, stack)
+                return true
+              end
+            end
+          when ListShape
+            return input_shape?(haystack.member.shape, needle, stack)
+          when MapShape
+            return input_shape?(haystack.value.shape, needle, stack)
+          end
+          false
+        end
+
+        def input_example_tag(api, shape)
+          params = ParamFormatter.new(ShapeRef.new(shape: shape))
+          note = "@note When passing #{shape.name} as input to an #{Client} "
+          note << "method, you can use a\n  vanilla Hash:\n\n      "
+          note << params.format.lines.join("      ")
+          tag(note)
+        end
+
+        def returned_by(api, shape)
+          methods = []
+
+          api.metadata['shapes'].each_structure do |struct|
+            struct.members.each do |member_name, member_ref|
+              if member_ref.shape == shape
+                methods << "Types::#{struct.name}##{member_name}"
+              end
+            end
+          end
+
+          api.operations.each do |operation_name, operation|
+            if operation.output && operation.output.shape == shape
+              methods << "Client##{operation_name}"
+            end
+          end
+          methods
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/docs/docstring_provider.rb

@@ -0,0 +1,66 @@
+module Aws
+  module Api
+    module Docs
+      class DocstringProvider
+
+        def initialize(docstrings)
+          @docstrings = docstrings
+        end
+
+        # @param [String] operation_name
+        # @return [String,nil]
+        def operation_docs(operation_name)
+          clean(@docstrings['operations'][operation_name])
+        end
+
+        # @param [String] shape_name
+        # @return [String,nil]
+        def shape_docs(shape_name)
+          clean(shape(shape_name)['base'])
+        end
+
+        # @param [String] shape_name
+        # @param [String] target
+        # @return [String,nil]
+        def shape_ref_docs(shape_name, target)
+          if ref_docs = shape(shape_name)['refs'][target]
+            clean(ref_docs)
+          else
+            shape_docs(shape_name)
+          end
+        end
+
+        private
+
+        def shape(name)
+          @docstrings['shapes'][name] || { 'base' => nil, 'refs' => {} }
+        end
+
+        def clean(value)
+          if value.nil?
+            ''
+          else
+            value.gsub(/\{(\S+)\}/, '`{\1}`').strip
+          end
+        end
+
+      end
+
+      class NullDocstringProvider
+
+        def operation_docs(operation_name)
+          nil
+        end
+
+        def shape_docs(shape_name)
+          nil
+        end
+
+        def shape_ref_docs(shape_name, target)
+          nil
+        end
+
+      end
+    end
+  end
+end

data/lib/aws-sdk-core/api/docs/operation_documenter.rb

@@ -0,0 +1,107 @@
+module Aws
+  module Api
+    module Docs
+      class OperationDocumenter
+
+        include Seahorse::Model
+        include Utils
+
+        def initialize(service_name, namespace)
+          @service_name = service_name
+          @namespace = namespace
+          @optname = 'options'
+        end
+
+        # @param [Symbol] method_name
+        # @param [Seahorse::Model::Opeation] operation
+        def document(method_name, operation)
+          m = YARD::CodeObjects::MethodObject.new(@namespace, method_name)
+          m.group = 'API Operations'
+          m.scope = :instance
+          m.parameters << [@optname, '{}']
+          m.docstring = operation.documentation
+          tags(method_name, operation).each do |tag|
+            m.add_tag(tag)
+          end
+        end
+
+        private
+
+        def tags(method_name, operation)
+          tags = []
+          tags += param_tags(method_name, operation)
+          tags += option_tags(method_name, operation)
+          tags += return_tags(method_name, operation)
+          tags += example_tags(method_name, operation)
+          tags += see_also_tags(method_name, operation)
+        end
+
+        def param_tags(method_name, operation)
+          []
+        end
+
+        def option_tags(method_name, operation)
+          operation_input_ref(operation).shape.members.map do |name, ref|
+            req = ref.required ? 'required,' : ''
+            type = input_type(ref)
+            tag("@option #{@optname} [#{req}#{type}] :#{name} #{ref.documentation}")
+          end
+        end
+
+        def return_tags(method_name, operation)
+          resp = '{Seahorse::Client::Response response}'
+          if operation.output && operation.output.shape.members.count > 0
+            rtype = output_type(operation.output)
+            returns = "[#{rtype}] Returns a #{resp} object which responds to "
+            returns << "the following methods:\n\n"
+            operation.output.shape.members.each do |mname, mref|
+              returns << "  * {#{rtype}##{mname} ##{mname}} => #{output_type(mref, true)}\n"
+            end
+          else
+            returns = "[Struct] Returns an empty #{resp}."
+          end
+          [tag("@return #{returns}")]
+        end
+
+        def example_tags(method_name, operation)
+          examples_from_disk(method_name, operation) + [
+            request_syntax_example(method_name, operation),
+            response_structure_example(method_name, operation),
+          ].compact
+        end
+
+        def examples_from_disk(method_name, operation)
+          dir = "examples/#{@service_name.downcase}/client/#{method_name}/*.md"
+          Dir.glob(dir).map do |path|
+            title = File.basename(path).split(/\./).first
+            title = title.sub(/^\d+_/, '').gsub(/_/, ' ')
+            title = title[0].upcase + title[1..-1]
+            tag("@example #{title}\n\n    " + File.read(path).lines.join('    '))
+          end
+        end
+
+        def request_syntax_example(method_name, operation)
+          example = RequestSyntaxExample.new(method_name, operation).to_str
+          parts = []
+          parts << "@example Request syntax with placeholder values\n\n"
+          parts += example.lines.map { |line| "  " + line }
+          tag(parts.join)
+        end
+
+        def response_structure_example(method_name, operation)
+          if example = ResponseStructureExample.new(method_name, operation).to_str
+            parts = []
+            parts << "@example Response structure\n\n"
+            parts += example.lines.map { |line| "  " + line }
+            tag(parts.join)
+          end
+        end
+
+        def see_also_tags(method_name, operation)
+          []
+        end
+
+      end
+    end
+  end
+end