gapic-generator 0.1.7 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7758f2d15a52b89f57555f192cf9d477cbfdbd9788578ba30b5e04d9c468ed85
-  data.tar.gz: ef2c5bd9924646eea488db7060dc654dc0cc2ff2ad1d5736e4f04cad217e0fe4
+  metadata.gz: 7d4dfb48094e9e52bcc6563460bfc9bf458496d81607777cecd231f497025e1a
+  data.tar.gz: a52c7434b5497d85543ac55149d54987ebfa950c191b1af7673a1f32fa58dd39
 SHA512:
-  metadata.gz: 6d28f3903643f3b86770f83538dcaa669668bcd9f89e85592bbc6680c95c13fc043b323cf406fa0fa37b0ad0ad21ed30bb56ed42c7a2be0b423cbfc4c0b7c423
-  data.tar.gz: a98b3d1af7be74a680e0b738b4d0753130f90c51ef71fb181a94189d1806b947338558826cd3e4f5b8c3315897546d2e36a1ce5d99d58dd501fd5aa5e8c3a76d
+  metadata.gz: be4a0672c23603bc0df2174f52d5cdc5ddd60264f322079f9c96e03bafcfa2b7fed187103ad864b19cc1a7e1ee3bb50eecc0e64a29e2534d4183c574fa5d1cc7
+  data.tar.gz: a80ec4c7604511c4b7d87fb4868dd928676aaaec205a32fc7cbda8facd52e7f9a347d1104ba8840df80f2e3df81f87b831483615540761ffdffd45575a129aa4

data/CHANGELOG.md

@@ -1,5 +1,24 @@
 # Release History for gapic-generator
 
+### 0.2.0 / 2020-03-23
+
+Generation updates:
+
+* Proto service documentation is rendered into client class YARD docs.
+* Generated Apache license is now well-formatted markdown.
+* YARD titles updated with the word "API".
+* Tweaks to the default summary and description text.
+* Generated rakefiles can run acceptance tests if present.
+* Switch the order of summary and description in the readmes.
+* Exempt a few more files (notably gemspec and rakefile) from rubocop.
+* Several formatting tweaks, including removal of redundant whitespace.
+
+Internal changes:
+
+* New configuration allows path helpers to be generated from outputs.
+* Moved presenters into lib so they can be changed/subclassed more easily.
+* Several additions to GemPresenter to support new features.
+
 ### 0.1.7 / 2020-03-18
 
 * Path modules extend self so helpers can be invoked on them directly

data/lib/gapic/formatting_utils.rb

@@ -33,10 +33,14 @@ module Gapic
       #
       # Tries to be smart about exempting preformatted text blocks.
       #
+      # @param api [Gapic::Schema::Api]
       # @param lines [Enumerable<String>]
+      # @param disable_xrefs [Boolean] (default is `false`) Disable linking to
+      #   cross-references, and render them simply as text. This can be used if
+      #   it is known that the targets are not present in the current library.
       # @return [Enumerable<String>]
       #
-      def format_doc_lines api, lines
+      def format_doc_lines api, lines, disable_xrefs: false
         # To detect preformatted blocks, this tracks the "expected" base indent
         # according to Markdown. Specifically, this is the effective indent of
         # previous block, which is normally 0 except if we're in a list item.
@@ -53,7 +57,7 @@ module Gapic
             in_block, base_indent = update_indent_state in_block, base_indent, line, indent
             if in_block == false
               line = escape_line_braces line
-              line = format_line_xrefs api, line
+              line = format_line_xrefs api, line, disable_xrefs
             end
           end
           line
@@ -104,11 +108,12 @@ module Gapic
         line
       end
 
-      def format_line_xrefs api, line
+      def format_line_xrefs api, line, disable_xrefs
         while (m = @xref_detector.match line)
           entity = api.lookup m[:addr]
           return line if entity.nil?
-          yard_link = yard_link_for_entity entity, m[:text]
+          text = m[:text]
+          yard_link = disable_xrefs ? text : yard_link_for_entity(entity, text)
           return line if yard_link.nil?
           line = "#{m[:pre]}#{yard_link}#{m[:post]}"
         end

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.1.7"
+    VERSION = "0.2.0"
   end
 end

data/lib/gapic/generators/base_generator.rb

@@ -55,14 +55,6 @@ module Gapic
           controller.class.all_helpers_from_path helpers_path
       end
 
-      def use_helpers! *helper_methods
-        helper_methods.each do |helper_method|
-          define_singleton_method helper_method do |*args|
-            controller.class.helpers.method(helper_method).call(*args)
-          end
-        end
-      end
-
       def controller
         # Each controller gets a new class, so multiple generators can be
         # active at the same time without stomping on each other.

data/lib/gapic/generators/default_generator.rb

@@ -15,6 +15,7 @@
 # limitations under the License.
 
 require "gapic/generators/base_generator"
+require "gapic/presenters"
 
 module Gapic
   module Generators
@@ -29,9 +30,6 @@ module Gapic
 
         # Configure to use a custom templates directory
         use_templates! File.join __dir__, "../../../templates/default"
-
-        # Configure these helper method to be used by the generator
-        use_helpers! :gem_presenter
       end
 
       # Disable Rubocop because we expect generate to grow and violate more
@@ -46,7 +44,7 @@ module Gapic
       def generate
         files = []
 
-        gem = gem_presenter @api
+        gem = Gapic::Presenters.gem_presenter @api
 
         gem.packages.each do |package|
           # Package level files

data/lib/gapic/helpers/filepath_helper.rb

@@ -0,0 +1,45 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "active_support/inflector"
+
+module Gapic
+  module Helpers
+    ##
+    # Helpers related to generating paths to ruby files (e.g. for require)
+    #
+    module FilepathHelper
+      ##
+      # Converts a ruby namespace string to a file path string.
+      def ruby_file_path api, namespace
+        file_path = ruby_file_path_for_namespace namespace
+        fix_file_path api, file_path
+      end
+
+      ##
+      # Converts a ruby namespace string to a file path string.
+      def ruby_file_path_for_namespace namespace
+        ActiveSupport::Inflector.underscore namespace
+      end
+
+      ##
+      # Corrects a namespace by replacing known bad values with good values.
+      def fix_file_path api, file_path
+        file_path.split("/").map { |node| api.fix_file_path node }.join("/")
+      end
+    end
+  end
+end

data/lib/gapic/helpers/namespace_helper.rb

@@ -0,0 +1,51 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "active_support/inflector"
+
+module Gapic
+  module Helpers
+    ##
+    # Helpers related to generating ruby namespaces
+    #
+    module NamespaceHelper
+      ##
+      # Looks up the ruby_package for a dot-separated address string to a new string
+      # and creates the corrected Ruby namespace
+      def ruby_namespace api, address
+        file = api.file_for address
+        address = address.dup
+        address[file.package] = file.ruby_package if file.ruby_package.present?
+        namespace = ruby_namespace_for_address address
+        fix_namespace api, namespace
+      end
+
+      ##
+      # Converts an array or dot-separated address string to a new string with
+      # Ruby double-semicolon separators.
+      def ruby_namespace_for_address address
+        address = address.split "." if address.is_a? String
+        address.reject(&:empty?).map(&:camelize).join "::"
+      end
+
+      ##
+      # Corrects a namespace by replacing known bad values with good values.
+      def fix_namespace api, namespace
+        namespace.split("::").map { |node| api.fix_namespace node }.join("::")
+      end
+    end
+  end
+end

data/lib/gapic/presenters.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+# Copyright 2020 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "gapic/presenters/enum_presenter"
+require "gapic/presenters/enum_value_presenter"
+require "gapic/presenters/field_presenter"
+require "gapic/presenters/file_presenter"
+require "gapic/presenters/gem_presenter"
+require "gapic/presenters/message_presenter"
+require "gapic/presenters/method_presenter"
+require "gapic/presenters/package_presenter"
+require "gapic/presenters/resource_presenter"
+require "gapic/presenters/sample_presenter"
+require "gapic/presenters/service_presenter"
+
+module Gapic
+  ##
+  # A namespace for presenter classes.
+  #
+  module Presenters
+    ##
+    # Return a gem presenter
+    #
+    # @param api [Gapic::Schema::Api] The api schema object
+    # @return [Gapic::Presenters::GemPresenter]
+    #
+    def self.gem_presenter api
+      GemPresenter.new api
+    end
+  end
+end

data/{templates/default/helpers → lib/gapic}/presenters/enum_presenter.rb

@@ -14,22 +14,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-require_relative "enum_value_presenter"
+module Gapic
+  module Presenters
+    ##
+    # A presenter for proto enums.
+    #
+    class EnumPresenter
+      def initialize enum
+        @enum = enum
+      end
 
-class EnumPresenter
-  def initialize enum
-    @enum = enum
-  end
-
-  def name
-    @enum.name
-  end
+      def name
+        @enum.name
+      end
 
-  def doc_description
-    @enum.docs_leading_comments
-  end
+      def doc_description
+        @enum.docs_leading_comments
+      end
 
-  def values
-    @values ||= @enum.values.map { |v| EnumValuePresenter.new v }
+      def values
+        @values ||= @enum.values.map { |v| EnumValuePresenter.new v }
+      end
+    end
   end
 end

data/{templates/default/helpers → lib/gapic}/presenters/enum_value_presenter.rb

@@ -14,20 +14,27 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-class EnumValuePresenter
-  def initialize value
-    @value = value
-  end
+module Gapic
+  module Presenters
+    ##
+    # A presenter for proto enum values.
+    #
+    class EnumValuePresenter
+      def initialize value
+        @value = value
+      end
 
-  def name
-    @value.name
-  end
+      def name
+        @value.name
+      end
 
-  def doc_description
-    @value.docs_leading_comments
-  end
+      def doc_description
+        @value.docs_leading_comments
+      end
 
-  def number
-    @value.number
+      def number
+        @value.number
+      end
+    end
   end
 end

data/lib/gapic/presenters/field_presenter.rb

@@ -0,0 +1,154 @@
+# frozen_string_literal: true
+
+# Copyright 2018 Google LLC
+#
+# Licensed under the Apache License, Version 2.0 (the "License");
+# you may not use this file except in compliance with the License.
+# You may obtain a copy of the License at
+#
+#     https://www.apache.org/licenses/LICENSE-2.0
+#
+# Unless required by applicable law or agreed to in writing, software
+# distributed under the License is distributed on an "AS IS" BASIS,
+# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+# See the License for the specific language governing permissions and
+# limitations under the License.
+
+require "active_support/inflector"
+require "gapic/helpers/namespace_helper"
+
+module Gapic
+  module Presenters
+    ##
+    # A presenter for proto fields.
+    #
+    class FieldPresenter
+      include Gapic::Helpers::NamespaceHelper
+
+      def initialize api, message, field
+        @api = api
+        @message = message
+        @field = field
+      end
+
+      def name
+        @field.name
+      end
+
+      def doc_types
+        field_doc_types @field, false
+      end
+
+      def doc_attribute_type
+        mode = @field.output_only? ? "r" : "rw"
+        "@!attribute [#{mode}] #{@field.name}"
+      end
+
+      def output_doc_types
+        field_doc_types @field, true
+      end
+
+      def doc_description
+        @field.docs_leading_comments
+      end
+
+      def default_value
+        single = default_singular_value
+        return "[#{single}]" if @field.repeated? && !@field.map?
+        single
+      end
+
+      def as_kwarg value: nil
+        "#{name}: #{value || name}"
+      end
+
+      # TODO: remove, only used in tests
+      def type_name
+        @field.type_name
+      end
+
+      def type_name_full
+        return nil if type_name.blank?
+        ruby_namespace @api, type_name
+      end
+
+      def message?
+        @field.message?
+      end
+
+      def enum?
+        @field.enum?
+      end
+
+      def repeated?
+        @field.repeated?
+      end
+
+      def map?
+        @field.map?
+      end
+
+      protected
+
+      def field_doc_types field, output
+        return field_map_type field.message, output if field.map?
+        base_type =
+          if field.message?
+            type = message_ruby_type field.message
+            output ? type : "#{type} | Hash"
+          elsif field.enum?
+            # TODO: handle when arg message is nil and enum is the type
+            message_ruby_type field.enum
+          else
+            case field.type
+            when 1, 2                              then "Float"
+            when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "Integer"
+            when 9, 12                             then "String"
+            when 8                                 then "Boolean"
+            else
+              "Object"
+            end
+          end
+        field.repeated? ? "Array<#{base_type}>" : base_type
+      end
+
+      def field_map_type entry_message, output
+        key_field = value_field = nil
+        entry_message.fields.each do |field|
+          key_field = field if field.name == "key"
+          value_field = field if field.name == "value"
+        end
+        class_name = output ? "Google::Protobuf::Map" : "Hash"
+        if key_field && value_field
+          key_type = field_doc_types key_field, output
+          value_type = field_doc_types value_field, output
+          "#{class_name}{#{key_type} => #{value_type}}"
+        else
+          class_name
+        end
+      end
+
+      def default_singular_value
+        if @field.message?
+          "{}"
+        elsif @field.enum?
+          # TODO: select the first non-0 enum value
+          ":#{@field.enum.values.first.name}"
+        else
+          case @field.type
+          when 1, 2                              then "3.5"
+          when 3, 4, 5, 6, 7, 13, 15, 16, 17, 18 then "42"
+          when 9, 12                             then "\"hello world\""
+          when 8                                 then "true"
+          else
+            "Object"
+          end
+        end
+      end
+
+      def message_ruby_type message
+        ruby_namespace @api, message.address.join(".")
+      end
+    end
+  end
+end