Describing how to create credentials explicitly in auth doc.

Also moving the from_service_account_* factory descriptions
into the newly added sections.

Author: dhermes

docs/gcloud-auth.rst

@@ -32,56 +32,132 @@ Overview
 Client-Provided Authentication
 ==============================
 
-Every package uses a :class:`Client <gcloud.client.Client>` as a base
-for interacting with an API. For example:
+Every package uses a :class:`Client <gcloud.client.Client>`
+as a base for interacting with an API.
+For example:
 
 .. code-block:: python
 
     from gcloud import datastore
     client = datastore.Client()
 
-Passing no arguments at all will "just work" if you've following the
-instructions in the :ref:`Overview`. The credentials are inferred from your
-local environment by using Google `Application Default Credentials`_.
+Passing no arguments at all will "just work" if you've followed the
+instructions in the :ref:`Overview`.
+The credentials are inferred from your local environment by using
+Google `Application Default Credentials`_.
 
 .. _Application Default Credentials: https://developers.google.com/identity/protocols/application-default-credentials
 
 Credential Discovery Precedence
 -------------------------------
 
-When loading the `Application Default Credentials`_, the library will check
-properties of your local environment in the following order
+When loading the `Application Default Credentials`_,
+the library will check properties of your local environment
+in the following order:
 
 #. Application running in Google App Engine
 #. JSON or PKCS12/P12 keyfile pointed to by
    ``GOOGLE_APPLICATION_CREDENTIALS`` environment variable
 #. Credentials provided by the Google Cloud SDK (via ``gcloud auth login``)
 #. Application running in Google Compute Engine
 
-Loading Credentials Explicitly
-------------------------------
+Explicit Credentials
+====================
 
-In addition, the
+The Application Default Credentials discussed above can be useful
+if your code needs to run in many different environments or
+if you just don't want authentication to be a focus in your code.
+
+However, you may want to be explicit because
+
+* your code will only run in one place
+* you may have code which needs to be run as a specific service account
+  every time (rather than with the locally inferred credentials)
+* you may want to use two separate accounts to simultaneously access data
+  from different projects
+
+In these situations, you can create an explicit
+:class:`Credentials <oauth2client.client.Credentials>` object suited to your
+environment.
+After creation,
+you can pass it directly to a :class:`Client <gcloud.client.Client>`:
+
+.. code:: python
+
+    client = Client(credentials=credentials)
+
+Google App Engine Environment
+-----------------------------
+
+To create :class:`credentials <oauth2client.appengine.AppAssertionCredentials>`
+just for Google App Engine:
+
+.. code:: python
+
+    from oauth2client.appengine import AppAssertionCredentials
+    credentials = AppAssertionCredentials([])
+
+Google Compute Engine Environment
+---------------------------------
+
+To create :class:`credentials <oauth2client.gce.AppAssertionCredentials>`
+just for Google Compute Engine:
+
+.. code:: python
+
+    from oauth2client.gce import AppAssertionCredentials
+    credentials = AppAssertionCredentials([])
+
+Service Accounts
+----------------
+
+A `service account`_ can be used with both a JSON keyfile and
+a PKCS12/P12 keyfile.
+
+Directly creating ``credentials`` in `oauth2client`_ for a service
+account is a rather complex process,
+so as a convenience, the
 :meth:`from_service_account_json() <gcloud.client.Client.from_service_account_json>`
 and
 :meth:`from_service_account_p12() <gcloud.client.Client.from_service_account_p12>`
-factories can be used if you know the specific type of credentials you'd
-like to use.
+factories are provided to create a :class:`Client <gcloud.client.Client>` with
+service account credentials.
+
+.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/
+
+For example, with a JSON keyfile:
 
 .. code:: python
 
     client = Client.from_service_account_json('/path/to/keyfile.json')
 
 .. tip::
 
-    Unless you have an explicit reason to use a PKCS12 key for your
-    service account, we recommend using a JSON key.
+    Unless you have a specific reason to use a PKCS12/P12 key for your
+    service account,
+    we recommend using a JSON key.
 
-Finally, if you are **familiar** with the `oauth2client`_ library, you can
-create a ``credentials`` object and pass it directly:
+User Accounts (3-legged OAuth 2.0) with a refresh token
+-------------------------------------------------------
 
-.. code:: python
+The majority of cases are intended to authenticate machines or
+workers rather than actual user accounts. However, it's also
+possible to call Google Cloud APIs with a user account via
+`OAuth 2.0`_.
 
-    client = Client(credentials=credentials)
+.. _OAuth 2.0: https://developers.google.com/identity/protocols/OAuth2
 
-.. _oauth2client: http://oauth2client.readthedocs.org/en/latest/
+.. tip::
+
+    A production application should **use a service account**,
+    but you may wish to use your own personal user account when first
+    getting started with the ``gcloud-python`` library.
+
+This is only supported via Application Default Credentials using
+``gcloud auth login`` as mentioned above.
+To create these credentials directly:
+
+.. code:: python
+
+    from oauth2client.client import GoogleCredentials
+    credentials = GoogleCredentials.get_application_default()