Class: Gapic::Presenters::GemPresenter

Inherits:
Object
  • Object
show all
Includes:
Helpers::FilepathHelper, Helpers::NamespaceHelper
Defined in:
lib/gapic/presenters/gem_presenter.rb

Overview

A presenter for gems.

Instance Method Summary collapse

Methods included from Helpers::NamespaceHelper

#ensure_absolute_namespace, #fix_namespace, #ruby_namespace, #ruby_namespace_for_address

Methods included from Helpers::FilepathHelper

#fix_file_path, #ruby_file_path, #ruby_file_path_for_namespace

Constructor Details

#initialize(api) ⇒ GemPresenter

Returns a new instance of GemPresenter.



31
32
33
34
35
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 31

def initialize api
  @api = api
  service_config = api.configuration[:common_services] ? nil : api.service_config
  @mixins_model = Gapic::Model::Mixins.new api.services.map(&:full_name), service_config, name
end

Instance Method Details

#api_id ⇒ Object 



171
172
173
174
175
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 171

def api_id
  raw_id = gem_config(:api_id) || @api.api_metadata.name
  return nil unless raw_id
  raw_id.include?(".") ? raw_id : "#{raw_id}.googleapis.com"
end

#api_shortname ⇒ Object 



177
178
179
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 177

def api_shortname
  gem_config(:api_shortname) || @api.api_metadata.short_name
end

#authors ⇒ Object 



112
113
114
115
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 112

def authors
  gem_config(:authors) ||
    ["Google LLC"]
end

#default_transport ⇒ :grpc, :rest

Returns:

  • (:grpc) —

    If gRPC is the default transport

  • (:rest) —

    if REST is the default transport



237
238
239
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 237

def default_transport
  @api.default_transport
end

#default_transport_name ⇒ String

Returns Pretty name of the default transport.

Returns:

  • (String) —

    Pretty name of the default transport



244
245
246
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 244

def default_transport_name
  @api.default_transport == :grpc ? "gRPC" : "REST"
end

#dependencies ⇒ Object 



261
262
263
264
265
266
267
268
269
270
271
272
273
274
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 261

def dependencies
  @dependencies ||= begin
    deps = { "gapic-common" => "~> 1.3" }
    deps["grpc-google-iam-v1"] = "~> 1.11" if iam_dependency?
    extra_deps = gem_config_dependencies
    deps.merge! mixins_model.dependencies if mixins_model.mixins?
    # extra deps should be last, overriding mixins or defaults
    deps.merge! extra_deps if extra_deps
    # google-iam-v1 is a superset of grpc-google-iam-v1, so if both are
    # listed, use only google-iam-v1.
    deps.delete "grpc-google-iam-v1" if deps.include? "google-iam-v1"
    deps
  end
end

#dependency_list ⇒ Object 



276
277
278
279
280
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 276

def dependency_list
  dependencies.to_a
              .map { |name, requirements| [name, Array(requirements)] }
              .sort_by { |name, _requirements| name }
end

#description ⇒ Object 



122
123
124
125
126
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 122

def description
  gem_config(:description) ||
    @api.api_metadata.description ||
    "#{name} is the official client library for the #{title} API."
end

#doc_tag_prefix ⇒ Object 



181
182
183
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 181

def doc_tag_prefix
  @api.api_metadata.doc_tag_prefix || api_shortname || api_id&.split(".")&.first
end

#email ⇒ Object 



117
118
119
120
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 117

def email
  gem_config(:email) ||
    "googleapis-packages@google.com"
end

#entrypoint_require ⇒ Object 



248
249
250
251
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 248

def entrypoint_require
  return "" unless packages?
  packages.first.package_require
end

#env_prefix ⇒ Object 



155
156
157
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 155

def env_prefix
  gem_config(:env_prefix)&.upcase
end

#extra_files ⇒ Object 



257
258
259
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 257

def extra_files
  ["README.md", "LICENSE.md", ".yardopts"]
end

#first_non_common_service ⇒ Object

Select the primary non-common service for documentation. Prioritize services with methods so that the README quickstart showcases a functional client. If all are empty (e.g., in unit tests), fall back to the first non-common service.



67
68
69
70
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 67

def first_non_common_service
  non_common = services.select { |service| service.common_service_delegate.nil? }
  non_common.find { |service| service.methods.any? } || non_common.first
end

#first_package_drift_json ⇒ String

Returns a drift manifest of the first package in a pretty JSON string form

Returns:

  • (String) 


299
300
301
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 299

def first_package_drift_json
  JSON.pretty_generate first_package_drift_manifest
end

#first_package_drift_manifest ⇒ Hash

Returns a hash with a drift_manifest of a first package in this gem (while the behaviour in case of multiple packages is clarified). See https://github.com/googleapis/googleapis/blob/master/gapic/metadata/gapic_metadata.proto

Returns:

  • (Hash) 


289
290
291
292
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 289

def first_package_drift_manifest
  return {} unless packages?
  packages.first.drift_manifest
end

#free_tier? ⇒ Boolean

Returns:

  • (Boolean) 


192
193
194
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 192

def free_tier?
  gem_config(:free_tier) || false
end

#gemspec_description ⇒ Object 



128
129
130
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 128

def gemspec_description
  description.gsub(/\s+/, " ").strip
end

#generate_grpc_clients? ⇒ Boolean

Returns Whether generation of gRPC clients is requested.

Returns:

  • (Boolean) —

    Whether generation of gRPC clients is requested.



229
230
231
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 229

def generate_grpc_clients?
  @api.generate_grpc_clients?
end

#generate_rest_clients? ⇒ Boolean

Returns Whether the generation of REST clients is requested and can be done because at least one method has rest bindings.

Returns:

  • (Boolean) —

    Whether the generation of REST clients is requested and can be done because at least one method has rest bindings.



222
223
224
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 222

def generate_rest_clients?
  @api.generate_rest_clients? && packages.any? { |package| !package.first_service_with_rest.nil? }
end

#generic_endpoint? ⇒ Boolean

Returns:

  • (Boolean) 


207
208
209
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 207

def generic_endpoint?
  gem_config(:generic_endpoint) || false
end

#homepage ⇒ Object 



150
151
152
153
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 150

def homepage
  gem_config(:homepage) ||
    "https://github.com/googleapis/googleapis"
end

#iam_dependency? ⇒ Boolean

Returns:

  • (Boolean) 


159
160
161
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 159

def iam_dependency?
  @api.files.map(&:name).any? { |f| f.start_with? "google/iam/v1/" }
end

#issue_tracker_url ⇒ Object 



185
186
187
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 185

def issue_tracker_url
  gem_config :issue_tracker_url
end

#library_documentation_url ⇒ Object 



163
164
165
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 163

def library_documentation_url
  gem_config(:library_documentation_url) || "https://rubydoc.info/gems/#{name}"
end

#license_name ⇒ Object 



253
254
255
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 253

def license_name
  "MIT"
end

#mixins? ⇒ Boolean

Whether there are mixin services that should be referenced in the services for this gem

Returns:

  • (Boolean) 


331
332
333
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 331

def mixins?
  @mixins_model.mixins?
end

#mixins_model ⇒ Gapic::Model::Mixins

The model for the mixin services

Returns:



340
341
342
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 340

def mixins_model
  @mixins_model
end

#name ⇒ Object 



80
81
82
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 80

def name
  gem_config :name
end

#namespace ⇒ Object 



84
85
86
87
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 84

def namespace
  gem_config(:namespace) ||
    fix_namespace(@api, name.split("-").map(&:camelize).join("::"))
end

#packages ⇒ Enumerable<Gapic::Presenters::PackagePresenter>

Returns:



40
41
42
43
44
45
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 40

def packages
  @packages ||= begin
    packages = @api.generate_files.map(&:package).uniq.sort
    packages.map { |p| PackagePresenter.new self, @api, p }.delete_if(&:empty?)
  end
end

#packages? ⇒ Boolean

Returns:

  • (Boolean) 


47
48
49
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 47

def packages?
  !packages.empty?
end

#product_documentation_url ⇒ Object 



167
168
169
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 167

def product_documentation_url
  gem_config(:product_documentation_url) || @api.api_metadata.documentation_url
end

#proto_files ⇒ Object 



72
73
74
75
76
77
78
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 72

def proto_files
  @proto_files ||= begin
    @api.files
        .select { |f| useful_proto_file? f }
        .map { |f| FilePresenter.new @api, f }
  end
end

#quick_start_service ⇒ Gapic::Presenters::ServicePresenter

The service to use for quick start samples. Normally this is simply the #first_non_common_service, but it can be overridden via a gem config.

Returns:



309
310
311
312
313
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 309

def quick_start_service
  preferred_service = gem_config :quick_start_service
  result = services.find { |svc| svc.name == preferred_service } if preferred_service
  result || first_non_common_service
end

#readme_description ⇒ Array<String>

Generates a description text for README files, accounting for markdown rendering and properly escaping variables.

Returns:

  • (Array<String>) —

    The description text as an array of lines.



138
139
140
141
142
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 138

def readme_description
  has_markdown = description.strip.start_with? "#"
  desc = has_markdown ? description.split("\n") : [description.gsub(/\s+/, " ").strip]
  Gapic::FormattingUtils.format_doc_lines @api, desc
end

#rest_numeric_enums? ⇒ Boolean

Returns:

  • (Boolean) 


214
215
216
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 214

def rest_numeric_enums?
  gem_config(:rest_numeric_enums) || false
end

#services ⇒ Enumerable<Gapic::Presenters::ServicePresenter>

Returns:



54
55
56
57
58
59
60
61
62
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 54

def services
  @services ||= begin
    files = @api.generate_files
    service_list = files.map(&:services).flatten
    mixin_service_names = mixins_model.mixin_services
    service_list.delete_if { |s| mixin_service_names.include? s.full_name }
    service_list.map { |s| ServicePresenter.new self, @api, s }
  end
end

#show_logging_docs? ⇒ Boolean

Whether the "Enabling Logging" section of the readme should appear. This is true if there is a quick-start service displayed in the readme.

Returns:

  • (Boolean) 


321
322
323
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 321

def show_logging_docs?
  packages? && !quick_start_service.usable_service_presenter.nil?
end

#summary ⇒ Object 



144
145
146
147
148
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 144

def summary
  gem_config(:summary) ||
    @api.api_metadata.summary ||
    "API Client library for the #{title} API"
end

#title ⇒ Object 



89
90
91
92
93
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 89

def title
  gem_config(:title) ||
    @api.api_metadata.title ||
    namespace.split("::").join(" ")
end

#version ⇒ Object 



95
96
97
98
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 95

def version
  gem_config(:version) ||
    "0.0.1"
end

#version_file_path ⇒ Object 



104
105
106
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 104

def version_file_path
  "#{version_require}.rb"
end

#version_name_full ⇒ Object 



108
109
110
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 108

def version_name_full
  "#{namespace}::VERSION"
end

#version_require ⇒ Object 



100
101
102
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 100

def version_require
  ruby_file_path @api, version_name_full
end

#yard_strict? ⇒ Boolean

Returns:

  • (Boolean) 


199
200
201
202
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 199

def yard_strict?
  # Default to true unless the config is explicitly set to "false"
  gem_config(:yard_strict).nil? || gem_config(:yard_strict)
end