gcloud 0.6.3 → 0.7.0

data/lib/gcloud/logging/sink.rb

@@ -0,0 +1,233 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 "gcloud/logging/sink/list"
+
+module Gcloud
+  module Logging
+    ##
+    # # Sink
+    #
+    # Used to export log entries outside Cloud Logging. When you create a sink,
+    # new log entries are exported. Cloud Logging does not send
+    # previously-ingested log entries to the sink's destination.
+    #
+    # Before creating the sink, ensure that you have granted
+    # `cloud-logs@google.com` permission to write logs to the destination. See
+    # [Permissions for writing exported
+    # logs](https://cloud.google.com/logging/docs/export/configure_export#setting_product_name_short_permissions_for_writing_exported_logs).
+    #
+    # You can retrieve an existing sink with {Project#sink}.
+    #
+    # @see https://cloud.google.com/logging/docs/api/tasks/exporting-logs
+    #   Exporting Logs With Sinks
+    # @see https://cloud.google.com/logging/docs/api/introduction_v2#kinds_of_log_sinks
+    #   Kinds of log sinks (API V2)
+    # @see https://cloud.google.com/logging/docs/api/#sinks Sinks (API V1)
+    # @see https://cloud.google.com/logging/docs/export/configure_export#setting_product_name_short_permissions_for_writing_exported_logs
+    #   Permissions for writing exported logs
+    #
+    # @example
+    #   require "gcloud"
+    #
+    #   gcloud = Gcloud.new
+    #   logging = gcloud.logging
+    #   storage = gcloud.storage
+    #
+    #   bucket = storage.create_bucket "my-logs-bucket"
+    #
+    #   # Grant owner permission to Cloud Logging service
+    #   email = "cloud-logs@google.com"
+    #   bucket.acl.add_owner "group-#{email}"
+    #
+    #   sink = logging.create_sink "my-sink",
+    #                              "storage.googleapis.com/#{bucket.id}"
+    #
+    class Sink
+      ##
+      # @private The gRPC Service object.
+      attr_accessor :service
+
+      ##
+      # @private The Google API Client object.
+      attr_accessor :grpc
+
+      ##
+      # @private Create an empty Sink object.
+      def initialize
+        @service = nil
+        @grpc = Google::Logging::V2::LogSink.new
+      end
+
+      ##
+      # The client-assigned sink identifier. Sink identifiers are limited to
+      # 1000 characters and can include only the following characters: `A-Z`,
+      # `a-z`, `0-9`, and the special characters `_-.`.
+      def name
+        @grpc.name
+      end
+
+      ##
+      # The export destination. See [Exporting Logs With
+      # Sinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs).
+      def destination
+        @grpc.destination
+      end
+
+      ##
+      # Updates the export destination. See [Exporting Logs With
+      # Sinks](https://cloud.google.com/logging/docs/api/tasks/exporting-logs).
+      def destination= destination
+        @grpc.destination = destination
+      end
+
+      ##
+      # An [advanced logs
+      # filter](https://cloud.google.com/logging/docs/view/advanced_filters)
+      # that defines the log entries to be exported. The filter must be
+      # consistent with the log entry format designed by the `version`
+      # parameter, regardless of the format of the log entry that was originally
+      # written to Cloud Logging.
+      def filter
+        @grpc.filter
+      end
+
+      ##
+      # Updates the [advanced logs
+      # filter](https://cloud.google.com/logging/docs/view/advanced_filters)
+      # that defines the log entries to be exported. The filter must be
+      # consistent with the log entry format designed by the `version`
+      # parameter, regardless of the format of the log entry that was originally
+      # written to Cloud Logging.
+      def filter= filter
+        @grpc.filter = filter
+      end
+
+      ##
+      # The log entry version used when exporting log entries from this sink.
+      # This version does not have to correspond to the version of the log entry
+      # when it was written to Cloud Logging.
+      def version
+        @grpc.output_version_format
+      end
+
+      ##
+      # Updates the log entry version used when exporting log entries from this
+      # sink. This version does not have to correspond to the version of the log
+      # entry when it was written to Cloud Logging. Accepted values are
+      # `:VERSION_FORMAT_UNSPECIFIED`, `:V2`, and `:V1`.
+      def version= version
+        @grpc.output_version_format = self.class.resolve_version(version)
+      end
+
+      ##
+      # Helper to determine if the sink's version is
+      # `VERSION_FORMAT_UNSPECIFIED`.
+      def unspecified?
+        !(v1? || v2?)
+      end
+
+      ##
+      # Helper to determine if the sink's version is `V2`.
+      def v2?
+        version == :V2
+      end
+
+      ##
+      # Helper to determine if the sink's version is `V1`.
+      def v1?
+        version == :V1
+      end
+
+      ##
+      # Updates the logs-based sink.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #   sink = logging.sink "severe_errors"
+      #   sink.filter = "logName:syslog AND severity>=ERROR"
+      #   sink.save
+      #
+      def save
+        ensure_service!
+        @grpc = service.update_sink name, destination, filter, version
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
+      end
+
+      ##
+      # Reloads the logs-based sink with current data from the Logging
+      # service.
+      def reload!
+        ensure_service!
+        @grpc = service.get_sink name
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
+      end
+      alias_method :refresh!, :reload!
+
+      ##
+      # Permanently deletes the logs-based sink.
+      #
+      # @return [Boolean] Returns `true` if the sink was deleted.
+      #
+      # @example
+      #   require "gcloud"
+      #
+      #   gcloud = Gcloud.new
+      #   logging = gcloud.logging
+      #   sink = logging.sink "severe_errors"
+      #   sink.delete
+      #
+      def delete
+        ensure_service!
+        service.delete_sink name
+        return true
+      rescue GRPC::BadStatus => e
+        raise Gcloud::Error.from_error(e)
+      end
+
+      ##
+      # @private New Sink from a Google::Logging::V2::LogSink object.
+      def self.from_grpc grpc, service
+        new.tap do |f|
+          f.grpc = grpc
+          f.service = service
+        end
+      end
+
+      ##
+      # @private Convert a version value to the gRPC enum value.
+      def self.resolve_version version
+        ver = version.to_s.upcase.to_sym
+        ver = Google::Logging::V2::LogSink::VersionFormat.resolve ver
+        return ver if ver
+        Google::Logging::V2::LogSink::VersionFormat::VERSION_FORMAT_UNSPECIFIED
+      end
+
+      protected
+
+      ##
+      # @private Raise an error unless an active connection to the service is
+      # available.
+      def ensure_service!
+        fail "Must have active connection to service" unless service
+      end
+    end
+  end
+end

data/lib/gcloud/logging/sink/list.rb

@@ -0,0 +1,97 @@
+# Copyright 2016 Google Inc. All rights reserved.
+#
+# 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
+#
+#     http://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 "delegate"
+
+module Gcloud
+  module Logging
+    class Sink
+      ##
+      # Sink::List is a special case Array with additional values.
+      class List < DelegateClass(::Array)
+        ##
+        # If not empty, indicates that there are more records that match
+        # the request and this value should be passed to continue.
+        attr_accessor :token
+
+        ##
+        # @private Create a new Sink::List with an array of Sink instances.
+        def initialize arr = []
+          super arr
+        end
+
+        ##
+        # Whether there is a next page of sinks.
+        def next?
+          !token.nil?
+        end
+
+        ##
+        # Retrieve the next page of sinks.
+        def next
+          return nil unless next?
+          ensure_service!
+          list_grpc = @service.list_sinks token: token
+          self.class.from_grpc list_grpc, @service
+        rescue GRPC::BadStatus => e
+          raise Gcloud::Error.from_error(e)
+        end
+
+        ##
+        # Retrieves all sinks by repeatedly loading {#next?} until {#next?}
+        # returns `false`. Returns the list instance for method chaining.
+        #
+        # @example
+        #   require "gcloud"
+        #
+        #   gcloud = Gcloud.new
+        #   logging = gcloud.logging
+        #   all_sinks = logging.sinks.all # Load all pages of sinks
+        #
+        def all
+          while next?
+            next_records = self.next
+            push(*next_records)
+            self.token = next_records.token
+          end
+          self
+        end
+
+        ##
+        # @private New Sink::List from a Google::Logging::V2::ListSinksResponse
+        # object.
+        def self.from_grpc grpc_list, service
+          sinks = new(Array(grpc_list.sinks).map do |grpc|
+            Sink.from_grpc grpc, service
+          end)
+          sinks.instance_eval do
+            @token = grpc_list.next_page_token
+            @token = nil if @token == ""
+            @service = service
+          end
+          sinks
+        end
+
+        protected
+
+        ##
+        # Raise an error unless an active service is available.
+        def ensure_service!
+          fail "Must have active service" unless @service
+        end
+      end
+    end
+  end
+end

data/lib/gcloud/pubsub.rb

@@ -1,4 +1,3 @@
-#--
 # Copyright 2015 Google Inc. All rights reserved.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -13,40 +12,34 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+
 require "gcloud"
 require "gcloud/pubsub/project"
 
-#--
-# Google Cloud Pub/Sub
 module Gcloud
   ##
   # Creates a new object for connecting to the Pub/Sub service.
   # Each call creates a new connection.
   #
-  # === Parameters
+  # For more information on connecting to Google Cloud see the [Authentication
+  # Guide](https://googlecloudplatform.github.io/gcloud-ruby/#/docs/guides/authentication).
   #
-  # +project+::
-  #   Project identifier for the Pub/Sub service you are connecting to.
-  #   (+String+)
-  # +keyfile+::
-  #   Keyfile downloaded from Google Cloud. If file path the file must be
-  #   readable. (+String+ or +Hash+)
-  # +scope+::
-  #   The OAuth 2.0 scopes controlling the set of resources and operations that
-  #   the connection can access. See {Using OAuth 2.0 to Access Google
-  #   APIs}[https://developers.google.com/identity/protocols/OAuth2]. (+String+
-  #   or +Array+)
+  # @param [String] project Project identifier for the Pub/Sub service you are
+  #   connecting to.
+  # @param [String, Hash] keyfile Keyfile downloaded from Google Cloud. If file
+  #   path the file must be readable.
+  # @param [String, Array<String>] scope The OAuth 2.0 scopes controlling the
+  #   set of resources and operations that the connection can access. See [Using
+  #   OAuth 2.0 to Access Google
+  #   APIs](https://developers.google.com/identity/protocols/OAuth2).
   #
   #   The default scope is:
   #
-  #   * +https://www.googleapis.com/auth/pubsub+
-  #
-  # === Returns
-  #
-  # Gcloud::Pubsub::Project
+  #   * `https://www.googleapis.com/auth/pubsub`
   #
-  # === Example
+  # @return [Gcloud::Pubsub::Project]
   #
+  # @example
   #   require "gcloud/pubsub"
   #
   #   pubsub = Gcloud.pubsub
@@ -65,7 +58,7 @@ module Gcloud
   end
 
   ##
-  # = Google Cloud Pub/Sub
+  # # Google Cloud Pub/Sub
   #
   # Google Cloud Pub/Sub is designed to provide reliable, many-to-many,
   # asynchronous messaging between applications. Publisher applications can
@@ -75,312 +68,361 @@ module Gcloud
   # applications.
   #
   # Gcloud's goal is to provide a API that is familiar and comfortable to
-  # Rubyists. Authentication is handled by Gcloud#pubsub. You can provide the
+  # Rubyists. Authentication is handled by {Gcloud#pubsub}. You can provide the
   # project and credential information to connect to the Pub/Sub service, or if
   # you are running on Google Compute Engine this configuration is taken care
   # of for you.
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   topic.publish "task completed"
+  # topic = pubsub.topic "my-topic"
+  # topic.publish "task completed"
+  # ```
   #
-  # To learn more about Pub/Sub, read the {Google Cloud Pub/Sub Overview
-  # }[https://cloud.google.com/pubsub/overview].
+  # To learn more about Pub/Sub, read the [Google Cloud Pub/Sub Overview
+  # ](https://cloud.google.com/pubsub/overview).
   #
-  # == Retrieving Topics
+  # ## Retrieving Topics
   #
   # A Topic is a named resource to which messages are sent by publishers.
-  # A Topic is found by its name. (See Project#topic)
+  # A Topic is found by its name. (See {Gcloud::Pubsub::Project#topic})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
-  #   topic = pubsub.topic "my-topic"
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
+  # topic = pubsub.topic "my-topic"
+  # ```
   #
-  # == Creating a Topic
+  # ## Creating a Topic
   #
-  # A Topic is created from a Project. (See Project#create_topic)
+  # A Topic is created from a Project. (See
+  # {Gcloud::Pubsub::Project#create_topic})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
-  #   topic = pubsub.create_topic "my-topic"
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
+  # topic = pubsub.create_topic "my-topic"
+  # ```
   #
-  # == Retrieving Subscriptions
+  # ## Retrieving Subscriptions
   #
   # A Subscription is a named resource representing the stream of messages from
-  # a single, specific Topic, to be delivered to the subscribing application.
-  # A Subscription is found by its name. (See Topic#subscription)
+  # a single, specific Topic, to be delivered to the subscribing application. A
+  # Subscription is found by its name. (See
+  # {Gcloud::Pubsub::Topic#subscription})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   subscription = topic.subscription "my-topic-subscription"
-  #   puts subscription.name
+  # topic = pubsub.topic "my-topic"
+  # subscription = topic.subscription "my-topic-subscription"
+  # puts subscription.name
+  # ```
   #
-  # == Creating a Subscription
+  # ## Creating a Subscription
   #
-  # A Subscription is created from a Topic. (See Topic#subscribe and
-  # Project#subscribe)
+  # A Subscription is created from a Topic. (See
+  # {Gcloud::Pubsub::Topic#subscribe} and {Gcloud::Pubsub::Project#subscribe})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   sub = topic.subscribe "my-topic-sub"
-  #   puts sub.name # => "my-topic-sub"
+  # topic = pubsub.topic "my-topic"
+  # sub = topic.subscribe "my-topic-sub"
+  # puts sub.name # => "my-topic-sub"
+  # ```
   #
   # The subscription can be created that specifies the number of seconds to
   # wait to be acknowledged as well as an endpoint URL to push the messages to:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   sub = topic.subscribe "my-topic-sub",
-  #                         deadline: 120,
-  #                         endpoint: "https://example.com/push"
+  # topic = pubsub.topic "my-topic"
+  # sub = topic.subscribe "my-topic-sub",
+  #                       deadline: 120,
+  #                       endpoint: "https://example.com/push"
+  # ```
   #
-  # == Publishing Messages
+  # ## Publishing Messages
   #
   # Messages are published to a topic. Any message published to a topic without
   # a subscription will be lost. Ensure the topic has a subscription before
-  # publishing. (See Topic#publish and Project#publish)
+  # publishing. (See {Gcloud::Pubsub::Topic#publish} and
+  # {Gcloud::Pubsub::Project#publish})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   msg = topic.publish "new-message"
+  # topic = pubsub.topic "my-topic"
+  # msg = topic.publish "new-message"
+  # ```
   #
   # Messages can also be published with attributes:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   msg = topic.publish "new-message",
-  #                       foo: :bar,
-  #                       this: :that
+  # topic = pubsub.topic "my-topic"
+  # msg = topic.publish "new-message",
+  #                     foo: :bar,
+  #                     this: :that
+  # ```
   #
   # Multiple messages can be published at the same time by passing a block:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   topic = pubsub.topic "my-topic"
-  #   msgs = topic.publish do |batch|
-  #     batch.publish "new-message-1", foo: :bar
-  #     batch.publish "new-message-2", foo: :baz
-  #     batch.publish "new-message-3", foo: :bif
-  #   end
+  # topic = pubsub.topic "my-topic"
+  # msgs = topic.publish do |batch|
+  #   batch.publish "new-message-1", foo: :bar
+  #   batch.publish "new-message-2", foo: :baz
+  #   batch.publish "new-message-3", foo: :bif
+  # end
+  # ```
   #
-  # == Pulling Messages
+  # ## Pulling Messages
   #
-  # Messages are pulled from a Subscription. (See Subscription#pull)
+  # Messages are pulled from a Subscription. (See
+  # {Gcloud::Pubsub::Subscription#pull})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   msgs = sub.pull
+  # sub = pubsub.subscription "my-topic-sub"
+  # msgs = sub.pull
+  # ```
   #
   # A maximum number of messages returned can also be specified:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub", max: 10
-  #   msgs = sub.pull
+  # sub = pubsub.subscription "my-topic-sub", max: 10
+  # msgs = sub.pull
+  # ```
   #
   # The request for messages can also block until messages are available.
-  # (See Subscription#wait_for_messages)
+  # (See {Gcloud::Pubsub::Subscription#wait_for_messages})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   msgs = sub.wait_for_messages
+  # sub = pubsub.subscription "my-topic-sub"
+  # msgs = sub.wait_for_messages
+  # ```
   #
-  # == Acknowledging a Message
+  # ## Acknowledging a Message
   #
   # Messages that are received can be acknowledged in Pub/Sub, marking the
   # message to be removed so it cannot be pulled again.
   #
   # A Message that can be acknowledged is called a ReceivedMessage.
   # ReceivedMessages can be acknowledged one at a time:
-  # (See ReceivedMessage#acknowledge!)
+  # (See {Gcloud::Pubsub::ReceivedMessage#acknowledge!})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   sub.pull.each { |msg| msg.acknowledge! }
+  # sub = pubsub.subscription "my-topic-sub"
+  # sub.pull.each { |msg| msg.acknowledge! }
+  # ```
   #
   # Or, multiple messages can be acknowledged in a single API call:
-  # (See Subscription#acknowledge)
+  # (See {Gcloud::Pubsub::Subscription#acknowledge})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   received_messages = sub.pull
-  #   sub.acknowledge received_messages
+  # sub = pubsub.subscription "my-topic-sub"
+  # received_messages = sub.pull
+  # sub.acknowledge received_messages
+  # ```
   #
-  # == Modifying a Deadline
+  # ## Modifying a Deadline
   #
   # A message must be acknowledged after it is pulled, or Pub/Sub will mark the
   # message for redelivery. The message acknowledgement deadline can delayed if
   # more time is needed. This will allow more time to process the message before
-  # the message is marked for redelivery. (See ReceivedMessage#delay!)
+  # the message is marked for redelivery. (See
+  # {Gcloud::Pubsub::ReceivedMessage#delay!})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   received_message = sub.pull.first
-  #   if received_message
-  #     puts received_message.message.data
-  #     # Delay for 2 minutes
-  #     received_message.delay! 120
-  #   end
+  # sub = pubsub.subscription "my-topic-sub"
+  # received_message = sub.pull.first
+  # if received_message
+  #   puts received_message.message.data
+  #   # Delay for 2 minutes
+  #   received_message.delay! 120
+  # end
+  # ```
   #
   # The message can also be made available for immediate redelivery:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   received_message = sub.pull.first
-  #   if received_message
-  #     puts received_message.message.data
-  #     # Mark for redelivery by setting the deadline to now
-  #     received_message.delay! 0
-  #   end
+  # sub = pubsub.subscription "my-topic-sub"
+  # received_message = sub.pull.first
+  # if received_message
+  #   puts received_message.message.data
+  #   # Mark for redelivery by setting the deadline to now
+  #   received_message.delay! 0
+  # end
+  # ```
   #
   # Multiple messages can be delayed or made available for immediate redelivery:
-  # (See Subscription#delay)
+  # (See {Gcloud::Pubsub::Subscription#delay})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   received_messages = sub.pull
-  #   sub.delay 120, received_messages
+  # sub = pubsub.subscription "my-topic-sub"
+  # received_messages = sub.pull
+  # sub.delay 120, received_messages
+  # ```
   #
-  # == Listening for Messages
+  # ## Listening for Messages
   #
-  # Long running workers are easy to create with +listen+, which runs an
+  # Long running workers are easy to create with `listen`, which runs an
   # infinitely blocking loop to process messages as they are received. (See
-  # Subscription#listen)
+  # {Gcloud::Pubsub::Subscription#listen})
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   sub.listen do |msg|
-  #     # process msg
-  #   end
+  # sub = pubsub.subscription "my-topic-sub"
+  # sub.listen do |msg|
+  #   # process msg
+  # end
+  # ```
   #
   # Messages are retrieved in batches for efficiency. The number of messages
-  # pulled per batch can be limited with the +max+ option:
+  # pulled per batch can be limited with the `max` option:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   sub.listen max: 20 do |msg|
-  #     # process msg
-  #   end
+  # sub = pubsub.subscription "my-topic-sub"
+  # sub.listen max: 20 do |msg|
+  #   # process msg
+  # end
+  # ```
   #
   # When processing time and the acknowledgement deadline are a concern,
   # messages can be automatically acknowledged as they are pulled with the
-  # +autoack+ option:
+  # `autoack` option:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new
+  # pubsub = gcloud.pubsub
   #
-  #   sub = pubsub.subscription "my-topic-sub"
-  #   sub.listen autoack: true do |msg|
-  #     # process msg
-  #   end
+  # sub = pubsub.subscription "my-topic-sub"
+  # sub.listen autoack: true do |msg|
+  #   # process msg
+  # end
+  # ```
   #
-  # == Working Across Projects
+  # ## Working Across Projects
   #
   # All calls to the Pub/Sub service use the same project and credentials
-  # provided to the Gcloud#pubsub method. However, it is common to reference
+  # provided to the {Gcloud#pubsub} method. However, it is common to reference
   # topics or subscriptions in other projects, which can be achieved by using
-  # the +project+ option. The main credentials must have permissions to the
+  # the `project` option. The main credentials must have permissions to the
   # topics and subscriptions in other projects.
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new # my-project-id
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new # my-project-id
+  # pubsub = gcloud.pubsub
   #
-  #   # Get a topic in the current project
-  #   my_topic = pubsub.topic "my-topic"
-  #   my_topic.name #=> "projects/my-project-id/topics/my-topic"
-  #   # Get a topic in another project
-  #   other_topic = pubsub.topic "other-topic", project: "other-project-id"
-  #   other_topic.name #=> "projects/other-project-id/topics/other-topic"
+  # # Get a topic in the current project
+  # my_topic = pubsub.topic "my-topic"
+  # my_topic.name #=> "projects/my-project-id/topics/my-topic"
+  # # Get a topic in another project
+  # other_topic = pubsub.topic "other-topic", project: "other-project-id"
+  # other_topic.name #=> "projects/other-project-id/topics/other-topic"
+  # ```
   #
   # It is possible to create a subscription in the current project that pulls
   # from a topic in another project:
   #
-  #   require "gcloud"
+  # ```ruby
+  # require "gcloud"
   #
-  #   gcloud = Gcloud.new # my-project-id
-  #   pubsub = gcloud.pubsub
+  # gcloud = Gcloud.new # my-project-id
+  # pubsub = gcloud.pubsub
   #
-  #   # Get a topic in another project
-  #   topic = pubsub.topic "other-topic", project: "other-project-id"
-  #   # Create a subscription in the current project that pulls from
-  #   # the topic in another project
-  #   sub = topic.subscribe "my-sub"
-  #   sub.name #=> "projects/my-project-id/subscriptions/my-sub"
-  #   sub.topic.name #=> "projects/other-project-id/topics/other-topic"
+  # # Get a topic in another project
+  # topic = pubsub.topic "other-topic", project: "other-project-id"
+  # # Create a subscription in the current project that pulls from
+  # # the topic in another project
+  # sub = topic.subscribe "my-sub"
+  # sub.name #=> "projects/my-project-id/subscriptions/my-sub"
+  # sub.topic.name #=> "projects/other-project-id/topics/other-topic"
+  # ```
   #
   module Pubsub
   end