add authorization guide + links to Google docs

fixes googleapis#483
fixes googleapis#479

docs/authorization.md

@@ -0,0 +1,52 @@
+With `gcloud-node` it's incredibly easy to get authorized and start using Google's APIs. You can set your credentials on a global basis as well as on a per-API basis. See each individual API section below to see how you can auth on a per-API-basis. This is useful if you want to use different accounts for different Google Cloud services.
+
+## On Google Compute Engine
+
+If you are running this client on Google Compute Engine, we handle authorization for you with no configuration. You just need to make sure that when you [set up the GCE instance][gce-how-to], you add the correct scopes for the APIs you want to access.
+
+``` js
+var config = {
+  projectId: 'grape-spaceship-123'
+};
+
+var gcloud = require('gcloud')(config);
+```
+
+## Elsewhere
+
+If you are not running this client on Google Compute Engine, you need a Google Developers service account. To create a service account:
+
+1. Visit the [Google Developers Console][dev-console].
+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.
+
+``` js
+var config = {
+  projectId: 'grape-spaceship-123',
+  keyFilename: '/path/to/keyfile.json'
+};
+
+var gcloud = require('gcloud')(config);
+```
+
+### The `config` object
+
+A `config` object requires the following properties:
+
+1. `projectId`
+
+2. One of the following:
+  1. `config.credentials` object containing `client_email` and `private_key` properties.
+  2. `config.keyFilename` path to a .json, .pem, or .p12 key file.
+  3. `GOOGLE_APPLICATION_CREDENTIALS` environment variable with a full path to your key file.
+
+**Note**: When using a .pem or .p12 key file, `config.email` is also required.
+
+[dev-console]: https://console.developers.google.com/project
+[gce-how-to]: https://cloud.google.com/compute/docs/authentication#using

docs/index.html

@@ -36,6 +36,7 @@
     <script src="site/components/docs/docs-directives.js"></script>
     <script src="site/components/docs/docs-services.js"></script>
     <script src="site/components/docs/docs-values.js"></script>
+    <script src="site/components/authorization/authorization.js"></script>
     <script src="site/components/faq/faq.js"></script>
     <script src="site/components/subpage/subpage-directive.js"></script>
     <script src="site/components/header/header-directive.js"></script>

docs/site/components/authorization/authorization.html

@@ -0,0 +1,19 @@
+<script id="authorization-header.html" type="text/ng-template">
+  <header header title="Authorization">
+    <div class="row row--right">
+      <div class="col margin-vertical">
+        <a href="https://github.com/GoogleCloudPlatform/gcloud-node/edit/master/docs/authorization.md"
+          class="v-btn">
+          <img src="site/img/icon-link-github.svg" />
+          Edit on GitHub
+        </a>
+      </div>
+    </div>
+  </header>
+</script>
+
+<div subpage
+  header-templateUrl="authorization-header.html"
+  title="Authorization">
+  <btf-markdown ng-include="'authorization.md'"></btf-markdown>
+</div>

docs/site/components/authorization/authorization.js

@@ -0,0 +1,15 @@
+angular
+  .module('gcloud.authorization', ['ngRoute', 'gcloud.subpage', 'btford.markdown'])
+  .config(function($routeProvider) {
+    'use strict';
+
+    $routeProvider.when('/authorization', {
+      controller: 'AuthorizationCtrl',
+      templateUrl: 'site/components/authorization/authorization.html'
+    });
+  })
+
+  .controller('AuthorizationCtrl', function($scope) {
+    'use strict';
+
+  });

docs/site/components/docs/docs.html

@@ -44,13 +44,13 @@ <h3 class="sub-heading">
       <div hljs>$ npm install --save gcloud</div>
       <div hljs>var gcloud = require('gcloud');</div>
       <p>
-        If you are running your app on Google App Engine or Google Compute Engine, you won't need to worry about supplying connection configuration options to <code>gcloud</code>&mdash; we figure that out for you.
+        If you are running your app on Google Compute Engine, you won't need to worry about supplying connection configuration options to <code>gcloud</code>&mdash; we figure that out for you.
       </p>
       <p>
         However, if you're running your app elsewhere, you will need to provide project details to authenticate API requests.
       </p>
       <div hljs>
-// App Engine and Compute Engine
+// Compute Engine
 var gcloud = require('gcloud');
 
 // Elsewhere
@@ -59,7 +59,7 @@ <h3 class="sub-heading">
   keyFilename: '/path/to/keyfile.json'
 });</div>
       <p>
-        The full set of options which can be passed to gcloud and sub-modules are <a href="#/docs/?method=gcloud">outlined here</a>.
+        The full set of options which can be passed to gcloud and sub-modules are <a href="#/authorization">outlined here</a>.
       </p>
     </article>
     <hr>
@@ -69,10 +69,8 @@ <h3>BigQuery Overview</h3>
       <p>
         The object returned from <code>gcloud.bigquery</code> gives you complete access to and control of your BigQuery datasets. You can work with existing ones, by using the <code>dataset</code> method, or create new ones with <code>createDataset</code>.
       </p>
-      <div hljs>
-var bigquery = gcloud.bigquery();</div>
       <p>
-        Follow along with the examples below to see how to query your datasets, create tables, import data from your Cloud Storage buckets, and more.
+        To learn more about BigQuery, see <a href="https://cloud.google.com/bigquery/what-is-bigquery">What is BigQuery?</a>
       </p>
     </article>
 
@@ -81,13 +79,8 @@ <h3>Datastore Overview</h3>
       <p>
         The <code>gcloud.datastore</code> object gives you some convenience methods, as well as exposes a <code>dataset</code> function. This will allow you to create a <code>dataset</code>, which is the object from which you will interact with the Google Cloud Datastore.
       </p>
-      <div hljs>
-var dataset = gcloud.datastore.dataset({
-  projectId: 'project-id',
-  keyFilename: '/path/to/keyfile.json'
-});</div>
-      <p ng-if="!isActiveUrl('/docs/datastore/dataset')">
-        See <a href="#/docs/{{version}}/datastore/dataset">the Dataset documentation</a> for examples of how to query the datastore, save entities, run a transaction, and others.
+      <p>
+        To learn more about Datastore, read the <a href="https://cloud.google.com/datastore/docs/concepts/overview">Google Cloud Datastore Concepts Overview</a>.
       </p>
     </article>
 
@@ -97,41 +90,28 @@ <h3>Pub/Sub Overview</h3>
         Google Cloud Pub/Sub is in Alpha status. As a result, it might be changed in backward-incompatible ways and is not recommended for production use. It is not subject to any SLA or deprecation policy.
       </p>
       <p>
-        The <code>gcloud.pubsub</code> method will return a <code>pubsub</code> object, allowing you to create topics, publish messages, subscribe to topics, and more. See the <a href="https://developers.google.com/pubsub/overview">Google Cloud Pub/Sub overview</a> for more information.
+        The <code>gcloud.pubsub</code> method will return a <code>pubsub</code> object, allowing you to create topics, publish messages, subscribe to topics, and more.
       </p>
-      <div hljs>
-var pubsub = gcloud.pubsub({
-  projectId: 'project-id',
-  keyFilename: '/path/to/keyfile.json'
-});</div>
       <p>
-        See the examples below, which demonstrate everything from creating a topic to subscribing to messages on a topic.
+        To learn more about Pub/Sub, see the <a href="https://developers.google.com/pubsub/overview">Google Cloud Pub/Sub overview</a>.
       </p>
     </article>
 
     <article ng-if="isActiveDoc('storage')">
       <h3>Storage Overview</h3>
       <p>
-        The <code>gcloud.storage</code> object contains a <code>bucket</code> function, which is how you will interact with your Google Cloud Storage bucket. See the guide on <a href="https://developers.google.com/storage">Google Cloud Storage</a> to create a bucket.
+        The <code>gcloud.storage</code> object contains a <code>bucket</code> function, which is how you will interact with your Google Cloud Storage bucket.
       </p>
-      <div hljs>
-var bucket = gcloud.storage().bucket('my-bucket');</div>
-      <h4>ACLs</h4>
       <p>
-        Google Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share files with other users and allow other users to access your buckets and files.
+        To learn more about Cloud Storage, see the <a href="https://cloud.google.com/storage/docs/overview">Google Cloud Storage overview</a>.
       </p>
+
+      <h4>ACLs</h4>
       <p>
-        Convenience methods are provided to perform common operations, such as the following.
+        Google Cloud Storage uses access control lists (ACLs) to manage object and bucket access. ACLs are the mechanism you use to share files with other users and allow other users to access your buckets and files.
       </p>
-      <div hljs>
-// Allow a user to read files from a bucket.
-bucket.acl.readers.addUser('email@example.com', function(err, aclObject) {});
-
-// Revoke file ownership permissions from a group.
-var myFile = bucket.file('my-file.txt');
-myFile.acl.owners.deleteGroup('group-id', function(err, aclObject) {});</div>
       <p>
-        See examples below for more on how to access your bucket to upload a file, read its files, create signed URLs, and more.
+        To learn more about ACLs, read this overview on <a href="https://cloud.google.com/storage/docs/access-control">Access Control</a>.
       </p>
     </article>
 

docs/site/components/subpage/subpage.html

@@ -56,6 +56,11 @@ <h1 class="logo">
           Documentation
         </a>
       </li>
+      <li>
+        <a href="#/authorization" ng-class="{ current: isActiveUrl('/authorization') }" title="Authorization">
+          Authorization
+        </a>
+      </li>
       <li>
         <a href="#/faq" ng-class="{ current: isActiveUrl('/faq') }" title="Frequently Asked Questions">
           FAQ

docs/site/css/main.css

@@ -725,6 +725,13 @@ ul {
   cursor: pointer;
 }
 
+.js {
+  display: block;
+  padding: .5em;
+  color: #333;
+  background: #F8F8F8;
+}
+
 /*
  Page Title
 */

docs/site/home.js

@@ -1,6 +1,7 @@
 angular
   .module('gcloud', [
     'ngRoute',
+    'gcloud.authorization',
     'gcloud.docs',
     'gcloud.faq',
     'gcloud.troubleshooting',

lib/bigquery/index.js

@@ -66,35 +66,20 @@ var SCOPES = ['https://www.googleapis.com/auth/bigquery'];
  * The examples below will demonstrate the different usage patterns your app may
  * need to support to retrieve a BigQuery object.
  *
- * The full set of options that can be passed to BigQuery are
- * [outlined here](#/docs/?method=gcloud).
- *
  * @alias module:bigquery
  * @constructor
  *
- * @param {object=} options - Configuration object.
+ * @param {object} options - [Configuration object](#/docs/?method=gcloud).
  *
  * @example
- * var gcloud = require('gcloud');
- *
- * //-
- * // Providing configuration details up-front.
- * //-
- * var myProject = gcloud({
+ * var gcloud = require('gcloud')({
  *   keyFilename: '/path/to/keyfile.json',
  *   projectId: 'my-project'
  * });
  *
  * var bigquery = myProject.bigquery();
  *
  * //-
- * // Overriding default configuration details.
- * //-
- * var bigquery = myProject.bigquery({
- *   keyFilename: '/path/to/another/keyfile.json'
- * });
- *
- * //-
  * // In the following examples from this page and the other modules (Dataset,
  * // Table, etc.), we are going to be using a dataset from
  * // data.gov (http://goo.gl/f2SXcb) of higher education institutions.

lib/datastore/dataset.js

@@ -66,16 +66,11 @@ var SCOPES = [
  * Interact with a dataset from the
  * [Google Cloud Datastore](https://developers.google.com/datastore/).
  *
- * The full set of options that can be passed to this method are
- * [outlined here](#/docs/?method=gcloud).
- *
  * @constructor
  * @alias module:datastore/dataset
  * @mixes module:datastore/request
  *
- * @param {object=} options - Configuration object.
- * @param {string=} options.projectId - Dataset ID. This is your project ID from
- *     the Google Developers Console.
+ * @param {object=} options - [Configuration object](#/docs/?method=gcloud).
  * @param {string=} options.apiEndpoint - Override the default API endpoint used
  *     to reach Datastore. This is useful for connecting to your local Datastore
  *     server (usually "http://localhost:8080").
@@ -94,6 +89,11 @@ var SCOPES = [
  *   projectId: 'my-project',
  *   apiEndpoint: 'http://localhost:8080'
  * });
+ *
+ * //-
+ * // The `process.env.DATASTORE_HOST` environment variable is also recognized.
+ * // If set, you may omit the `apiEndpoint` option.
+ * //-
  */
 function Dataset(options) {
   if (!(this instanceof Dataset)) {

lib/datastore/index.js

@@ -62,28 +62,18 @@ var Dataset = require('./dataset');
  * @alias module:datastore
  * @constructor
  *
- * @example
- * var gcloud = require('gcloud');
+ * @param {object} options - [Configuration object](#/docs/?method=gcloud).
  *
- * //-
- * // Providing configuration details up-front.
- * //-
- * var myProject = gcloud({
+ * @example
+ * var gcloud = require('gcloud')({
  *   keyFilename: '/path/to/keyfile.json',
  *   projectId: 'my-project'
  * });
  *
  * var dataset = gcloud.dataset();
- *
- * //-
- * // Overriding default configuration details.
- * //-
- * var dataset = myProject.datastore.dataset({
- *   keyFilename: '/path/to/another/keyfile.json'
- * });
  */
-function Datastore(config) {
-  this.config = config || {};
+function Datastore(options) {
+  this.config = options || {};
 }
 
 /*! Developer Documentation

lib/index.js

@@ -58,45 +58,8 @@ var util = require('./common/util.js');
  * 2. Provide them at the time of instantiation of sub-modules, e.g. a Datastore
  * dataset, a Cloud Storage bucket, etc.
  *
- * If you are using Google App Engine or Google Compute Engine, your connection
- * details are handled for you. You won't have to worry about specifying these,
- * however you may find it advantageous to provide a `projectId` at
- * instantiation.
- *
- * To specify the configuration details up-front, invoke the gcloud module,
- * passing in an object. The properties defined on this object will be persisted
- * to the instantiation of every sub-module. It's important to note that you can
- * override any of these defaults when you invoke a sub-module later.
- *
- * You can invoke this module as many times as your project warrants. Each time,
- * your provided configuration will remain isolated to the returned gcloud
- * module.
- *
- * To authenticate API requests,
- * [google-auth-library](https://github.com/google/google-auth-library-nodejs)
- * is used to detect the environment your project is running in. Use the
- * following guide to determine the appropriate configuration.
- *
- * <h4>Google Compute Engine</h4>
- *
- *   - No configuration necessary!
- *
- * <h4>Google App Engine Production</h4>
- *
- *   - No configuration necessary!
- *
- * <h4>Other</h4>
-
- *   - Provide `config.projectId`
- *   - Use one of the following:
- *     - `config.credentials` object containing `client_email` and `private_key`
- *       properties.
- *     - `config.keyFilename` path to a .json, .pem, or .p12 key file.
- *     - `GOOGLE_APPLICATION_CREDENTIALS` environment variable with a full path
- *        to your key file.
- *
- *   **Note**: When using a .pem or .p12 key file, `config.email` is also
- *   required.
+ * See our [Authorization Guide](#/authorization) for how to obtain the
+ * necessary credentials for connecting to your project.
  *
  * @alias module:gcloud
  * @constructor