Merge pull request #985 from tseaver/bigquery-devx-client_authz_confi…

…gure

Start DX docs for bigquery:  client authorization / configuration.

docs/_static/js/main.js

@@ -15,8 +15,10 @@ $('.headerlink').parent().each(function() {
 
 $('.side-nav').children('ul:nth-child(2)').children().each(function() {
   var itemName = $(this).text();
-    if (itemName !== 'Datastore' && itemName !== 'Storage' &&
-        itemName !== 'Pub/Sub') {
+    if (itemName !== 'Datastore' &&
+        itemName !== 'Storage' &&
+        itemName !== 'Pub/Sub' &&
+        itemName !== 'BigQuery') {
       $(this).css('padding-left','2em');
   }
 });
@@ -27,6 +29,10 @@ if ($('#cloud-datastore-in-10-seconds').length)
   apiQsSection = $('#cloud-datastore-in-10-seconds');
 else if ($('#cloud-storage-in-10-seconds').length)
   apiQsSection = $('#cloud-storage-in-10-seconds');
+else if ($('#cloud-pubsub-in-10-seconds').length)
+  apiQsSection = $('#cloud-pubsub-in-10-seconds');
+else if ($('#cloud-bigquery-in-10-seconds').length)
+  apiQsSection = $('#cloud-bigquery-in-10-seconds');
 
 if(apiQsSection) {
   var apiQsSubSections = apiQsSection.children('div');

docs/bigquery-usage.rst

@@ -0,0 +1,57 @@
+.. toctree::
+  :maxdepth: 0
+  :hidden:
+
+========
+BigQuery
+========
+
+Using the API
+=============
+
+Authorization / Configuration
+-----------------------------
+
+- Use :class:`Client <gcloud.bigquery.client.Client>` objects to configure
+  your applications.
+
+- :class:`Client <gcloud.bigquery.client.Client>` objects hold both a ``project``
+  and an authenticated connection to the PubSub service.
+
+- The authentication credentials can be implicitly determined from the
+  environment or directly via
+  :meth:`from_service_account_json <gcloud.bigquery.client.Client.from_service_account_json>`
+  and
+  :meth:`from_service_account_p12 <gcloud.bigquery.client.Client.from_service_account_p12>`.
+
+- After setting ``GOOGLE_APPLICATION_CREDENTIALS`` and ``GCLOUD_PROJECT``
+  environment variables, create an instance of
+  :class:`Client <gcloud.bigquery.client.Client>`.
+
+  .. doctest::
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client()
+
+- Override the credentials inferred from the environment by passing explicit
+  ``credentials`` to one of the alternative classmethods, `from_service_account_json`:
+
+  .. doctest::
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client.from_service_account_json('/path/to/creds.json')
+
+  or `from_service_account_p12`:
+
+  .. doctest::
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client.from_service_account_p12('/path/to/creds.p12', 'jrandom@example.com')
+
+- Override the project inferred from the environment by passing an explicit
+  ``project`` to the constructor, or to either of the alternative classmethods:
+
+  .. doctest::
+
+     >>> from gcloud import bigquery
+     >>> client = bigquery.Client(project='PROJECT_ID')

docs/index.rst

@@ -18,6 +18,7 @@
   pubsub-usage
   pubsub-subscription
   pubsub-topic
+  bigquery-usage
 
 
 Getting started