Documentation Link Generator

Generates links out from SDK docs to API docs.

aws-sdk-core/lib/aws-sdk-core.rb

@@ -157,6 +157,7 @@ module Api
     module Docs
       autoload :Builder, 'aws-sdk-core/api/docs/builder'
       autoload :ClientTypeDocumenter, 'aws-sdk-core/api/docs/client_type_documenter'
+      autoload :Crosslink, 'aws-sdk-core/api/docs/crosslink'
       autoload :DocstringProvider, 'aws-sdk-core/api/docs/docstring_provider'
       autoload :NullDocstringProvider, 'aws-sdk-core/api/docs/docstring_provider'
       autoload :OperationDocumenter, 'aws-sdk-core/api/docs/operation_documenter'

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

@@ -17,6 +17,7 @@ def initialize(svc_module)
           @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']
@@ -143,7 +144,7 @@ def document_client_operations(namespace)
         end
 
         def document_client_operation(namespace, method_name, operation)
-          documenter = OperationDocumenter.new(@svc_name, namespace)
+          documenter = OperationDocumenter.new(@svc_name, namespace, @uid)
           documenter.document(method_name, operation)
         end
 

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

@@ -43,6 +43,7 @@ def docstring(api, shape)
         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
 
@@ -84,6 +85,14 @@ def input_example_tag(api, shape)
           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 = []
 

aws-sdk-core/lib/aws-sdk-core/api/docs/crosslink.rb

@@ -0,0 +1,44 @@
+module Aws
+  module Api
+    module Docs
+      module Crosslink
+
+        EXCLUDE_UIDS = [
+          "apigateway",
+          "budgets",
+          "cloudsearch",
+          "cloudsearchdomain",
+          "discovery",
+          "elastictranscoder",
+          "es",
+          "glacier",
+          "importexport",
+          "iot",
+          "iot-data",
+          "machinelearning",
+          "rekognition",
+          "s3",
+          "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

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

@@ -6,10 +6,11 @@ class OperationDocumenter
         include Seahorse::Model
         include Utils
 
-        def initialize(service_name, namespace)
+        def initialize(service_name, namespace, uid)
           @service_name = service_name
           @namespace = namespace
           @optname = 'options'
+          @uid = uid
         end
 
         # @param [Symbol] method_name
@@ -137,7 +138,11 @@ def response_structure_example(method_name, operation)
         end
 
         def see_also_tags(method_name, operation)
-          []
+          if Crosslink.taggable?(@uid)
+            [tag(Crosslink.tag_string(@uid, operation.name))]
+          else
+            []
+          end
         end
 
       end

tasks/docs.rake

@@ -35,6 +35,7 @@ desc 'Generate the API documentation.'
 task 'docs' => ['docs:clobber', 'docs:update_readme'] do
   env = {}
   env['DOCSTRINGS'] = '1'
+  env['BASEURL'] = 'http://docs.aws.amazon.com/'
   env['SITEMAP_BASEURL'] = 'http://docs.aws.amazon.com/sdkforruby/api/'
   sh(env, 'bundle exec yard')
 end