diff --git a/docs/authentication.md b/docs/authentication.md
index 7c26d1481ec7..c0b8767ec16a 100644
--- a/docs/authentication.md
+++ b/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
diff --git a/docs/faq.md b/docs/faq.md
index 64c2e28d46e8..1831db2fadd2 100644
--- a/docs/faq.md
+++ b/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.
diff --git a/package.json b/package.json
index 79b0e2fa44bd..5c69fb4be795 100644
--- a/package.json
+++ b/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",
diff --git a/packages/bigquery/src/index.js b/packages/bigquery/src/index.js
index dac804a44d67..c0e9055300b3 100644
--- a/packages/bigquery/src/index.js
+++ b/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
- * // data.gov 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)) {
diff --git a/packages/bigtable/src/index.js b/packages/bigtable/src/index.js
index 457f14847de7..6db595df0bf3 100644
--- a/packages/bigtable/src/index.js
+++ b/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'
- * });
- *
* //-
* // Creating a Cluster
* //
diff --git a/packages/compute/src/index.js b/packages/compute/src/index.js
index 03dc658039cc..c23fffc9b9f2 100644
--- a/packages/compute/src/index.js
+++ b/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)) {
diff --git a/scripts/docs.buildOverview.js b/scripts/docs.buildOverview.js
new file mode 100644
index 000000000000..529233c4d5be
--- /dev/null
+++ b/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;
\ No newline at end of file
diff --git a/scripts/overview.template.html b/scripts/overview.template.html
new file mode 100644
index 000000000000..57819a127221
--- /dev/null
+++ b/scripts/overview.template.html
@@ -0,0 +1,44 @@
+This class allows you interact with <%= title %>.
+
+First, install `<%= pkgJson.name %>` with npm:
+
+
+$ npm install --save <%= pkgJson.name %>
+
+
+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.
+
+Compute Engine
+
+<% if (umbrellaView) { %>
+var <%= instanceName || className %> = require('<%= pkgJson.name %>')();
+<% } else { %>
+var gcloud = require('google-cloud');
+var <%= instanceName || className %> = gcloud.<%= className %>();
+<% } %>
+
+
+Elsewhere
+
+<% 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'
+});
+<% } %>
+
+
+The full set of options which can be passed to `<%= pkgJson.name %>` are
+outlined in our
+[Authentication guide](#/docs/<%= className %>/<%= pkgJson.version %>/guides/authentication).
\ No newline at end of file
diff --git a/test/docs.js b/test/docs.js
index cc17453bd9fe..cc0356dcbb39 100644
--- a/test/docs.js
+++ b/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\')'