gapic-generator 0.1.5 → 0.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 87900df01c425c43c7c7ac1a46965b2324af78eb6c56b91e6cfe36eb0abf3d56
-  data.tar.gz: 3f72d4b99665d5e235332854e4bbd4cc69f181e08e66fff9a2444cdbd9f44693
+  metadata.gz: c3adc22eae54587c0d4ddebad747dc1efb90ed8973c6a617a4df8f3120cee027
+  data.tar.gz: c7c531f3e6e0da489acc866000007bdcd7001e585f98763cf4eeeb68c677c627
 SHA512:
-  metadata.gz: 89550d2af9728e7efdb9a3813fa50bf237dc8322057fce25653fba88aae3871672e50af88d0844e4c2ff34d725734236500e5c17cf0db889e0d517a67852760e
-  data.tar.gz: 653271d51b4f3142d99b21cee2dff0146ddea8768a3d2d128cad0fc3914a498cac532223b53773145a33c57d5167059d1d2c8fd29b17b66d51bf7cb7c1d792d8
+  metadata.gz: 7c9181069a5107c008cb3c276420f0f36421e0ef3fe37ac63f10fc3c00a87bb7c80444c371a084c3b8dfcf19f79b5e32939f6c8a611a1956e9837e4d421296fb
+  data.tar.gz: 648db155b410c7613a8f67d53b9f1319b4e784e54baf4d3f238221b4de0526438d6279af3fc14a53d2f5e5bfd8d85f5a0eeefc6542d8d92fc502870ec9a4ad8d

data/CHANGELOG.md

@@ -1,5 +1,60 @@
 # Release History for gapic-generator
 
+### 0.3.0 / 2020-04-10
+
+* Detect when a resource is referenced implicitly via child_type, and generate path helpers.
+* Update grpc-google-iam-v1 dependency to require the latest version.
+* Generated require graph is more sane and does not include cycles.
+* The bundler entrypoint now loads the entire gem for wrapper gems.
+* Generated readmes are more useful and include a quickstart.
+* Package and service modules now have basic documentation.
+* Overloads for methods now have basic explanatory documentation, including how to pass an empty request.
+* Request object documentation no longer duplicates the method documentation.
+
+### 0.2.3 / 2020-04-06
+
+* No changes
+
+### 0.2.2 / 2020-03-31
+
+* Updates to common protos, especially core types which were more than a year old.
+
+### 0.2.1 / 2020-03-26
+
+* Fix service address for LRO operation clients.
+* Tweak sample task names for wrapper-gem Rakefiles.
+
+### 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
+* Trigger IAM dependency for IAM V1 files other than iam_policy.proto
+
+### 0.1.6 / 2020-03-17
+
+* Generated libraries now depend on gapic-common 0.2
+* Convert cross-reference syntax in proto docs to YARD cross-reference links.
+* Preserve call options in LROs
+* Fix implicit kwarg warnings under Ruby 2.7
+
 ### 0.1.5 / 2020-03-13
 
 * More improvements to escaping of curly braces.

data/lib/gapic/formatting_utils.rb

@@ -22,25 +22,25 @@ module Gapic
   #
   module FormattingUtils
     @brace_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*[^`\\])?\{(?<inside>[^\s][^}]*)\}(?<post>.*)\z/m
+    @xref_detector = /\A(?<pre>[^`]*(`[^`]*`[^`]*)*)?\[(?<text>[\w\.]+)\]\[(?<addr>[\w\.]+)\](?<post>.*)\z/m
     @list_element_detector = /\A\s*(\*|\+|-|[0-9a-zA-Z]+\.)\s/
 
     class << self
       ##
-      # Given an enumerable of lines, escape braces that look like yardoc type
-      # links. Tries to be smart about handling only braces that would be
-      # interpreted by yard (i.e. those that are not part of preformatted text
-      # blocks).
+      # Given an enumerable of lines, performs yardoc formatting, including:
+      # * Interpreting cross-references identified as described in AIP 192
+      # * Escaping literal braces that look like yardoc type links
       #
+      # 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 escape_braces lines
-        # This looks for braces that:
-        # * Are opened and closed on the same line
-        # * Are not nested
-        # * Are not located between backticks
-        # * Are not in a preformatted block
-        #
+      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.
@@ -55,7 +55,10 @@ module Gapic
             in_block = nil
           else
             in_block, base_indent = update_indent_state in_block, base_indent, line, indent
-            line = escape_line_braces line if in_block == false
+            if in_block == false
+              line = escape_line_braces line
+              line = format_line_xrefs api, line, disable_xrefs
+            end
           end
           line
         end
@@ -104,6 +107,54 @@ module Gapic
         end
         line
       end
+
+      def format_line_xrefs api, line, disable_xrefs
+        while (m = @xref_detector.match line)
+          entity = api.lookup m[:addr]
+          return line if entity.nil?
+          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
+        line
+      end
+
+      ##
+      # Generate a YARD-style cross-reference for the given entity.
+      #
+      # @param entity [Gapic::Schema::Proto] the entity to link to
+      # @param text [String] the text for the link
+      # @return [String] YARD cross-reference syntax
+      #
+      def yard_link_for_entity entity, text
+        # As a special case, omit the service "google.longrunning.Operations"
+        # and its methods. This is because the generator creates
+        # service-specific copies of the operations client, rather than a
+        # Google::Longrunning::Operations::Client class, and there is in
+        # general no way to tell what the actual service-specific namespace is.
+        return text if entity.address[0, 3] == ["google", "longrunning", "Operations"]
+
+        case entity
+        when Gapic::Schema::Service
+          "{#{convert_address_to_ruby entity}::Client #{text}}"
+        when Gapic::Schema::Method
+          "{#{convert_address_to_ruby entity.parent}::Client##{entity.name.underscore} #{text}}"
+        when Gapic::Schema::Message, Gapic::Schema::Enum, Gapic::Schema::EnumValue
+          "{#{convert_address_to_ruby entity} #{text}}"
+        when Gapic::Schema::Field
+          "{#{convert_address_to_ruby entity.parent}##{entity.name} #{text}}"
+        end
+      end
+
+      def convert_address_to_ruby entity
+        file = entity.containing_file
+        api = file.containing_api
+        address = entity.address
+        address = address.join "." if address.is_a? Array
+        address = address.sub file.package, file.ruby_package if file.ruby_package&.present?
+        address.split(".").reject(&:empty?).map(&:camelize).map { |node| api.fix_namespace node }.join("::")
+      end
     end
   end
 end

data/lib/gapic/generator/version.rb

@@ -16,6 +16,6 @@
 
 module Gapic
   module Generator
-    VERSION = "0.1.5"
+    VERSION = "0.3.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
@@ -65,16 +63,17 @@ module Gapic
         end
 
         # Gem level files
-        files << g("gem/gitignore.erb", ".gitignore",                   gem: gem)
-        files << g("gem/version.erb",   "lib/#{gem.version_file_path}", gem: gem)
-        files << g("gem/gemspec.erb",   "#{gem.name}.gemspec",          gem: gem)
-        files << g("gem/gemfile.erb",   "Gemfile",                      gem: gem)
-        files << g("gem/rakefile.erb",  "Rakefile",                     gem: gem)
-        files << g("gem/readme.erb",    "README.md",                    gem: gem)
-        files << g("gem/changelog.erb", "CHANGELOG.md",                 gem: gem)
-        files << g("gem/rubocop.erb",   ".rubocop.yml",                 gem: gem)
-        files << g("gem/yardopts.erb",  ".yardopts",                    gem: gem)
-        files << g("gem/license.erb",   "LICENSE.md",                   gem: gem)
+        files << g("gem/gitignore.erb",  ".gitignore",                   gem: gem)
+        files << g("gem/version.erb",    "lib/#{gem.version_file_path}", gem: gem)
+        files << g("gem/gemspec.erb",    "#{gem.name}.gemspec",          gem: gem)
+        files << g("gem/gemfile.erb",    "Gemfile",                      gem: gem)
+        files << g("gem/rakefile.erb",   "Rakefile",                     gem: gem)
+        files << g("gem/readme.erb",     "README.md",                    gem: gem)
+        files << g("gem/changelog.erb",  "CHANGELOG.md",                 gem: gem)
+        files << g("gem/rubocop.erb",    ".rubocop.yml",                 gem: gem)
+        files << g("gem/yardopts.erb",   ".yardopts",                    gem: gem)
+        files << g("gem/license.erb",    "LICENSE.md",                   gem: gem)
+        files << g("gem/entrypoint.erb", "lib/#{gem.name}.rb",           gem: gem)
 
         gem.proto_files.each do |proto_file|
           files << g("proto_docs/proto_file.erb", "proto_docs/#{proto_file.docs_file_path}", file: proto_file)

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