aws-sdk-core 2.11.549

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

@@ -0,0 +1,223 @@
+require 'erb'
+
+module Aws
+  module Api
+    module Docs
+      class Builder
+
+        DOC_SRC = File.expand_path('../../../../../../doc-src/', __FILE__)
+
+        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']
+          @uid = @api.metadata['uid']
+          @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.exist?(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.exist?(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.exist?(path)
+          render(path)
+        end
+
+        def render(path)
+          svc_name = @svc_name
+          api = @api
+          full_name = @full_name
+          ERB.new(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, @uid)
+          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>Default Delay:</th><th>Default 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,118 @@
+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 << see_also_tag(api, shape) if redirectable?(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 see_also_tag(api, shape)
+          tag(Crosslink.tag_string(api.metadata["uid"], shape.name))
+        end
+
+        def redirectable?(api, shape)
+          Crosslink.taggable?(api.metadata["uid"]) && shape.name
+        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/crosslink.rb

@@ -0,0 +1,43 @@
+module Aws
+  module Api
+    module Docs
+      module Crosslink
+
+        EXCLUDE_UIDS = [
+          "apigateway",
+          "budgets",
+          "cloudsearch",
+          "cloudsearchdomain",
+          "discovery",
+          "elastictranscoder",
+          "es",
+          "glacier",
+          "importexport",
+          "iot",
+          "iot-data",
+          "machinelearning",
+          "rekognition",
+          "sdb",
+          "swf"
+        ]
+
+        def self.tag_string(uid, name)
+          path = "#{ENV['BASEURL']}goto/WebAPI/#{uid}/#{name}"
+          "@see #{path} AWS API Documentation"
+        end
+
+        def self.taggable?(uid)
+          uid && ENV['BASEURL'] && !exclude?(uid)
+        end
+
+        private
+        def self.exclude?(uid)
+          EXCLUDE_UIDS.any? do |service|
+            uid.match(/^#{service}/)
+          end
+        end
+
+      end
+    end
+  end
+end

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

@@ -0,0 +1,75 @@
+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]
+            docs = clean(ref_docs)
+            # Running through kramdown to catch unclosed tags that
+            # break the client doc pages, see Aws::RDS::Client
+            # for an example.
+            begin
+              require 'kramdown'
+              Kramdown::Document.new(docs, input: 'html').to_kramdown.strip
+            rescue LoadError
+              docs
+            end
+          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