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 



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

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 



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

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

#authors ⇒ Object 



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

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



233
234
235
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 233

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



240
241
242
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 240

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

#dependencies ⇒ Object 



257
258
259
260
261
262
263
264
265
266
267
268
269
270
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 257

def dependencies
  @dependencies ||= begin
    deps = { "gapic-common" => "~> 1.2" }
    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 



272
273
274
275
276
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 272

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

#description ⇒ Object 



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

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

#doc_tag_prefix ⇒ Object 



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

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

#email ⇒ Object 



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

def email
  gem_config(:email) ||
    "[email protected]"
end

#entrypoint_require ⇒ Object 



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

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

#env_prefix ⇒ Object 



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

def env_prefix
  gem_config(:env_prefix)&.upcase
end

#extra_files ⇒ Object 



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

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

#first_non_common_service ⇒ Object 



64
65
66
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 64

def first_non_common_service
  services.find { |service| service.common_service_delegate.nil? }
end

#first_package_drift_json ⇒ String

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

Returns:

  • (String) 


295
296
297
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 295

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) 


285
286
287
288
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 285

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

#free_tier? ⇒ Boolean

Returns:

  • (Boolean) 


188
189
190
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 188

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

#gemspec_description ⇒ Object 



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

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.



225
226
227
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 225

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.



218
219
220
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 218

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

#generic_endpoint? ⇒ Boolean

Returns:

  • (Boolean) 


203
204
205
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 203

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

#homepage ⇒ Object 



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

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

#iam_dependency? ⇒ Boolean

Returns:

  • (Boolean) 


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

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

#issue_tracker_url ⇒ Object 



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

def issue_tracker_url
  gem_config :issue_tracker_url
end

#library_documentation_url ⇒ Object 



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

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

#license_name ⇒ Object 



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

def license_name
  "MIT"
end

#mixins? ⇒ Boolean

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

Returns:

  • (Boolean) 


327
328
329
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 327

def mixins?
  @mixins_model.mixins?
end

#mixins_model ⇒ Gapic::Model::Mixins

The model for the mixin services

Returns:



336
337
338
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 336

def mixins_model
  @mixins_model
end

#name ⇒ Object 



76
77
78
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 76

def name
  gem_config :name
end

#namespace ⇒ Object 



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

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 



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

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

#proto_files ⇒ Object 



68
69
70
71
72
73
74
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 68

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:



305
306
307
308
309
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 305

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.



134
135
136
137
138
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 134

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) 


210
211
212
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 210

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) 


317
318
319
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 317

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

#summary ⇒ Object 



140
141
142
143
144
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 140

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

#title ⇒ Object 



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

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

#version ⇒ Object 



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

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

#version_file_path ⇒ Object 



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

def version_file_path
  "#{version_require}.rb"
end

#version_name_full ⇒ Object 



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

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

#version_require ⇒ Object 



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

def version_require
  ruby_file_path @api, version_name_full
end

#yard_strict? ⇒ Boolean

Returns:

  • (Boolean) 


195
196
197
198
 
# File 'lib/gapic/presenters/gem_presenter.rb', line 195

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