build-prep

;

docs/authentication.md

@@ -1,14 +1,12 @@
-## With `google-cloud`
+## Authenticating with this module
 
-With `google-cloud` it's incredibly easy to get authenticated 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.
+It's incredibly easy to get authenticated 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.
 
 ```js
 var config = {
   projectId: 'grape-spaceship-123',
   keyFilename: '/path/to/keyfile.json'
 };
-
-var gcloud = require('google-cloud')(config);
 ```
 
 ### The `config` object

docs/faq.md

@@ -1,4 +1,4 @@
-## How do I use `gcloud-node` with Google Compute Engine?
+## How do I use this module with Google Compute Engine?
 
 If you are running this client on Google Compute Engine, we handle authentication 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.
 

package.json

@@ -10,6 +10,7 @@
     "istanbul": "^0.3.5",
     "jscs": "^2.1.1",
     "jshint": "^2.9.1",
+    "lodash.template": "^4.3.0",
     "mitm": "^1.1.0",
     "mocha": "^3.0.1",
     "propprop": "^0.3.0",

packages/bigquery/src/index.js

@@ -46,39 +46,19 @@ var Table = require('./table.js');
 var PKG = require('../package.json');
 
 /**
- * The examples below will demonstrate the different usage patterns your app may
- * need to support to retrieve a BigQuery object.
+ * 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.
+ *
+ * We will create a table with the correct schema, import the public CSV file
+ * into that table, and query it for data.
  *
  * @alias module:bigquery
  * @constructor
  *
- * @classdesc
- * The object returned from `gcloud.bigquery` gives you complete access to and
- * control of your BigQuery datasets. You can work with existing ones, by using
- * the `dataset` method, or create new ones with `createDataset`.
- *
- * To learn more about BigQuery, see
- * [What is BigQuery?](https://cloud.google.com/bigquery/what-is-bigquery)
+ * @resource [What is BigQuery?]{@link https://cloud.google.com/bigquery/what-is-bigquery}
  *
  * @param {object} options - [Configuration object](#/docs).
- *
- * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'my-project'
- * });
- *
- * var bigquery = gcloud.bigquery();
- *
- * //-
- * // In the following examples from this page and the other modules (Dataset,
- * // Table, etc.), we are going to be using a dataset from
- * // <a href="http://goo.gl/f2SXcb">data.gov</a> of higher education
- * // institutions.
- * //
- * // We will create a table with the correct schema, import the public CSV
- * // file into that table, and query it for data.
- * //-
  */
 function BigQuery(options) {
   if (!(this instanceof BigQuery)) {

packages/bigtable/src/index.js

@@ -42,39 +42,20 @@ var Table = require('./table.js');
 var PKG = require('../package.json');
 
 /**
- * Interact with
- * [Google Cloud Bigtable](https://cloud.google.com/bigtable/).
- *
- * @constructor
  * @alias module:bigtable
- *
- * @classdesc
- * The `gcloud.bigtable` object allows you interact with Google Cloud Bigtable.
- *
- * To learn more about Bigtable, read the
- * [Google Cloud Bigtable Concepts Overview](https://cloud.google.com/bigtable/docs/concepts)
+ * @constructor
  *
  * @resource [Creating a Cloud Bigtable Cluster]{@link https://cloud.google.com/bigtable/docs/creating-compute-instance}
+ * @resource [Google Cloud Bigtable Concepts Overview]{@link https://cloud.google.com/bigtable/docs/concepts}
  *
  * @throws {error} If a cluster is not provided.
  * @throws {error} If a zone is not provided.
  *
- * @param {object=} options - [Configuration object](#/docs).
+ * @param {object=} options - [Configuration object]({moduleRoot}/guides/authentication).
  * @param {string} options.cluster - The cluster name that hosts your tables.
  * @param {string|module:compute/zone} options.zone - The zone in which your
  *     cluster resides.
  *
- * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'my-project'
- * });
- *
- * var bigtable = gcloud.bigtable({
- *   zone: 'us-central1-b',
- *   cluster: 'gcloud-node'
- * });
- *
  * //-
  * // <h3>Creating a Cluster</h3>
  * //

packages/compute/src/index.js

@@ -83,31 +83,12 @@ var Zone = require('./zone.js');
 var PKG = require('../package.json');
 
 /**
- * A Compute object allows you to interact with the Google Compute Engine API.
- * Using this object, you can access your instances with {module:compute/vm},
- * disks with {module:compute/disk}, and firewalls with
- * {module:compute/firewall}.
- *
  * @alias module:compute
  * @constructor
  *
- * @classdesc
- * The object returned from `gcloud.compute` gives you complete control of your
- * Compute Engine virtual machines, disks, networks, snapshots, addresses,
- * firewalls, and more.
- *
- * To learn more about Compute Engine, see
- * [What is Google Compute Engine?](https://cloud.google.com/compute/docs)
+ * @resource [What is Google Compute Engine?]{@link https://cloud.google.com/compute/docs}
  *
  * @param {object} options - [Configuration object](#/docs).
- *
- * @example
- * var gcloud = require('google-cloud')({
- *   keyFilename: '/path/to/keyfile.json',
- *   projectId: 'grape-spaceship-123'
- * });
- *
- * var gce = gcloud.compute();
  */
 function Compute(options) {
   if (!(this instanceof Compute)) {

scripts/docs.buildOverview.js

@@ -0,0 +1,93 @@
+/**
+ * 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.
+ */
+
+'use strict';
+
+var fs = require('fs');
+var join = require('path').join;
+var template = require('lodash.template');
+
+var TEMPLATE_FILE = fs.readFileSync(join(__dirname, 'overview.template.html'));
+
+var CONFIG = {
+  bigquery: {
+    title: 'Google BigQuery'
+  },
+
+  bigtable: {
+    title: 'Google Cloud Bigtable'
+  },
+
+  compute: {
+    title: 'Google Compute Engine',
+    instanceName: 'gce'
+  },
+
+  datastore: {
+    title: 'Google Cloud Datastore'
+  },
+
+  dns: {
+    title: 'Google Cloud DNS'
+  },
+
+  language: {
+    title: 'Google Cloud Natural Language'
+  },
+
+  logging: {
+    title: 'Google Cloud Logging'
+  },
+
+  prediction: {
+    title: 'Google Prediction API'
+  },
+
+  pubsub: {
+    title: 'Google Cloud Pub/Sub'
+  },
+
+  resource: {
+    title: 'Google Cloud Resource Manager'
+  },
+
+  storage: {
+    title: 'Google Cloud Storage',
+    instanceName: 'gcs'
+  },
+
+  translate: {
+    title: 'Google Translate API'
+  },
+
+  vision: {
+    title: 'Google Cloud Vision'
+  }
+};
+
+module.exports = function(className) {
+  var config = CONFIG[className];
+
+  return template(TEMPLATE_FILE)({
+    pkgJson: require(join('..', 'packages', className, 'package.json')),
+    title: config.title,
+    instanceName: config.instanceName,
+    className: className,
+    umbrellaView: true
+  });
+};
+
+module.exports.CONFIG = CONFIG;

scripts/overview.template.html

@@ -0,0 +1,44 @@
+This class allows you interact with <%= title %>.
+
+First, install `<%= pkgJson.name %>` with npm:
+
+<div hljs language="bash">
+$ npm install --save <%= pkgJson.name %>
+</div>
+
+If you are running your app on Google Compute Engine, you won't need to worry
+about supplying connection configuration options to `<%= pkgJson.name %>`— we
+figure that out for you.
+
+However, if you're running your app elsewhere, you will need to provide project
+details to authenticate API requests.
+
+<h4>Compute Engine</h4>
+<div hljs language="javascript">
+<% if (umbrellaView) { %>
+var <%= instanceName || className %> = require('<%= pkgJson.name %>')();
+<% } else { %>
+var gcloud = require('google-cloud');
+var <%= instanceName || className %> = gcloud.<%= className %>();
+<% } %>
+</div>
+
+<h4>Elsewhere</h4>
+<div hljs language="javascript">
+<% if (umbrellaView) { %>
+var <%= instanceName || className %> = require('<%= pkgJson.name %>')({
+  projectId: 'grape-spaceship-123',
+  keyFilename: '/path/to/keyfile.json'
+});
+<% } else { %>
+var gcloud = require('google-cloud');
+var <%= instanceName || className %> = gcloud.<%= className %>({
+  projectId: 'grape-spaceship-123',
+  keyFilename: '/path/to/keyfile.json'
+});
+<% } %>
+</div>
+
+The full set of options which can be passed to `<%= pkgJson.name %>` are
+outlined in our
+[Authentication guide](#/docs/<%= className %>/<%= pkgJson.version %>/guides/authentication).

test/docs.js

@@ -16,10 +16,12 @@
 
 'use strict';
 
+var format = require('string-format-obj');
 var fs = require('fs');
 var gcloud = require('../packages/google-cloud');
 var glob = require('glob');
 var mitm = require('mitm');
+var packageOverviewConfigs = require('../scripts/docs.buildOverview.js');
 var prop = require('propprop');
 var vm = require('vm');
 
@@ -119,7 +121,29 @@ describe('documentation', function() {
     }
 
     fileDocBlocks.methods.forEach(function(method) {
-      var code = method.examples.map(prop('code')).join('\n')
+      var code = method.examples.map(prop('code')).join('\n');
+
+      var pkgConfig = packageOverviewConfigs.CONFIG[method.id.toLowerCase()];
+
+      if (pkgConfig) {
+        // Create code to initialize the variable that the class's prototype
+        // methods use.
+        var init = format('var {instanceName} = new {className}({config});', {
+          instanceName: pkgConfig.instanceName || method.id.toLowerCase(),
+          className: 'require(\'../packages/' + method.id.toLowerCase() + '\')',
+          config: JSON.stringify({
+            // All of the minimum required options our APIs expect.
+            projectId: 'grape-spaceship-123',
+            cluster: 'cluster',
+            zone: 'zone',
+            key: 'apiKey'
+          })
+        });
+
+        code = init + code;
+      }
+
+      code = code
         .replace(
           /require\(\'google-cloud\'\)/g,
           'require(\'../packages/google-cloud\')'