Merge pull request #66 from blowmage/storage-documentation

Update the README to match the agreed on format.
Improve the storage documentation code samples.

Fixes #54

README.md

@@ -7,14 +7,86 @@
 
 This client supports the following Google Cloud Platform services:
 
-* [Google Cloud Datastore](https://cloud.google.com/products/cloud-datastore)
+* [Google Cloud Datastore](https://cloud.google.com/datastore/)
+* [Google Cloud Storage](https://cloud.google.com/storage/)
+
+If you need support for other Google APIs, check out the [Google API Ruby Client library](https://github.com/google/google-api-ruby-client).
 
 ## Quick Start
 
 ```sh
 $ gem install gcloud
 ```
 
+### Authorization
+
+You need a Google Developers service account to use the Google Cloud services. To create a service account:
+
+1. Visit the [Google Developers Console](https://console.developers.google.com/project).
+2. Create a new project or click on an existing project.
+3. Navigate to **APIs & auth** > **APIs section** and turn on the following APIs (you may need to enable billing in order to use these services):
+  * Google Cloud Datastore API
+  * Google Cloud Storage
+  * Google Cloud Storage JSON API
+4. Navigate to **APIs & auth** > **Credentials** and then:
+  * If you want to use a new service account, click on **Create new Client ID** and select **Service account**. After the account is created, you will be prompted to download the JSON key file that the library uses to authorize your requests.
+  * If you want to generate a new key for an existing service account, click on **Generate new JSON key** and download the JSON key file.
+
+You will use the **Project ID** and **JSON file** to connect to services with gcloud.
+
+### Datastore
+
+[Google Cloud Datastore](https://cloud.google.com/datastore/) ([docs](https://cloud.google.com/datastore/docs)) is a fully managed, schemaless database for storing non-relational data. Cloud Datastore automatically scales with your users and supports ACID transactions, high availability of reads and writes, strong consistency for reads and ancestor queries, and eventual consistency for all other queries.
+
+Follow the [activation instructions](https://cloud.google.com/datastore/docs/activate) to use the Google Cloud Datastore API with your project.
+
+See the [gcloud-ruby Datastore API documentation](http://googlecloudplatform.github.io/gcloud-ruby/docs/master/Gcloud/Storage.html) to learn how to interact with the Cloud Datastore using this library.
+
+```ruby
+dataset = Gcloud::Datastore.dataset "my-todo-project-id",
+                                    "/path/to/keyfile.json"
+
+# Create a new task to demo datastore
+demo_task = Gcloud::Datastore::Entity.new
+demo_task.key = Gcloud::Datastore::Key.new "Task", "datastore-demo"
+demo_task[:description] = "Demonstrate Datastore functionality"
+demo_task[:completed] = false
+
+# Save the new task
+dataset.save demo_task
+
+# Run a query for all completed tasks
+query = Gcloud::Datastore::Query.new.kind("Task").
+  where("completed", "=", true)
+completed_tasks = dataset.run query
+```
+
+### Storage
+
+[Google Cloud Storage](https://cloud.google.com/storage/) ([docs](https://cloud.google.com/datastore/docs)) allows you to store data on Google infrastructure with very high reliability, performance and availability, and can be used to distribute large data objects to users via direct download.
+
+See the [gcloud-ruby Storage API documentation](http://googlecloudplatform.github.io/gcloud-ruby/docs/master/Gcloud/Storage.html) to learn how to connect to Cloud Storage using this library.
+
+```ruby
+storage = Gcloud::Storage.project "my-todo-project-id",
+                                  "/path/to/keyfile.json"
+
+bucket = storage.find_bucket "task-attachments"
+
+file = bucket.find_file "path/to/my-file.ext"
+
+# Download the file to the local file system
+file.download "/tasks/attachments/#{file.name}"
+
+# Copy the file to a backup bucket
+backup = storage.find_bucket "task-attachment-backups"
+file.copy backup, file.name
+```
+
+# Supported Ruby Versions
+
+gcloud is supported on Ruby 1.9.3+.
+
 ## Contributing
 
 Contributions to this library are always welcome and highly encouraged.

lib/gcloud/storage.rb

@@ -37,6 +37,8 @@ module Storage
     # @param keyfile [String] the path to the keyfile you downloaded from
     # Google Cloud. The file must readable.
     # @return [Gcloud::Storage::Connection] new connection
+    #
+    # See Gcloud::Storage::Project
     def self.project project = ENV["STORAGE_PROJECT"],
                      keyfile = ENV["STORAGE_KEYFILE"]
       credentials = Gcloud::Storage::Credentials.new keyfile

lib/gcloud/storage/bucket.rb

@@ -97,6 +97,15 @@ def delete options = {}
 
       ##
       # Retrieves a list of files matching the criteria.
+      #
+      #   storage = Gcloud::Storage.project
+      #   bucket = storage.find_bucket "my-bucket"
+      #   files = bucket.files
+      #   files.each do |file|
+      #     puts file.name
+      #   end
+      #
+      # See Gcloud::Storage::File
       def files
         ensure_connection!
         resp = connection.list_files name
@@ -111,6 +120,13 @@ def files
 
       ##
       # Retrieves a file matching the path.
+      #
+      #   storage = Gcloud::Storage.project
+      #   bucket = storage.find_bucket "my-bucket"
+      #   file = bucket.find_file "path/to/my-file.ext"
+      #   puts file.name
+      #
+      # See Gcloud::Storage::File
       def find_file path
         ensure_connection!
         resp = connection.get_file name, path
@@ -125,6 +141,17 @@ def find_file path
       # Create a new Gcloud::Storeage::File object by providing a
       # File object to upload and the path to store it with.
       #
+      #   storage = Gcloud::Storage.project
+      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket.create_file "path/to/local.file.ext"
+      #
+      # Additionally, a destination path can be specified.
+      #
+      #   storage = Gcloud::Storage.project
+      #   bucket = storage.find_bucket "my-bucket"
+      #   bucket.create_file "path/to/local.file.ext",
+      #                      "destination/path/file.ext"
+      #
       # A chunk_size value can be provided in the options to be used
       # in resumable uploads. This value is the number of bytes per
       # chunk and must be divisible by 256KB. If it is not divisible
@@ -134,6 +161,8 @@ def find_file path
       #   bucket.create_file "path/to/local.file.ext",
       #                      "destination/path/file.ext",
       #                      chunk_size: 1024*1024 # 1 MB chunk
+      #
+      # See Gcloud::Storage::File
       def create_file file, path = nil, options = {}
         ensure_connection!
         # TODO: Raise if file doesn't exist

lib/gcloud/storage/project.rb

@@ -22,14 +22,27 @@ module Gcloud
   module Storage
     ##
     # Represents the Project that the Buckets and Files belong to.
+    #
+    # Gcloud::Storage::Project is the main object for interacting with
+    # Google Storage. Gcloud::Storage::Bucket objects are created,
+    # read, updated, and deleted by Gcloud::Storage::Project.
+    #
+    #   storage = Gcloud::Storage.project "my-todo-project",
+    #                                     "/path/to/keyfile.json"
+    #   bucket = storage.find_bucket "my-bucket"
+    #   file = bucket.find_file "path/to/my-file.ext"
+    #
+    # See Gcloud::Storage.project
     class Project
       ##
       # The Connection object.
       attr_accessor :connection #:nodoc:
 
       ##
-      # Creates a new Connection instance.
-      def initialize project, credentials
+      # Creates a new Project instance.
+      #
+      # See Gcloud::Storage.project
+      def initialize project, credentials #:nodoc:
         @connection = Connection.new project, credentials
       end
 
@@ -41,6 +54,14 @@ def project
 
       ##
       # Retrieves a list of buckets for the given project.
+      #
+      #   storage = Gcloud::Storage.project
+      #   buckets = storage.buckets
+      #   buckets.each do |bucket|
+      #     puts bucket.name
+      #   end
+      #
+      # See Gcloud::Storage::Bucket
       def buckets
         resp = connection.list_buckets
         if resp.success?
@@ -54,6 +75,12 @@ def buckets
 
       ##
       # Retrieves bucket by name.
+      #
+      #   storage = Gcloud::Storage.project
+      #   bucket = storage.find_bucket "my-bucket"
+      #   puts bucket.name
+      #
+      # See Gcloud::Storage::Bucket
       def find_bucket bucket_name
         resp = connection.get_bucket bucket_name
         if resp.success?
@@ -74,6 +101,8 @@ def find_bucket bucket_name
       # specify the wanted behavior in the call:
       #
       #   bucket = project.create_bucket "my-bucket", retries: 5
+      #
+      # See Gcloud::Storage::Bucket
       def create_bucket bucket_name, options = {}
         resp = connection.insert_bucket bucket_name, options
         if resp.success?