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

@@ -40,7 +40,7 @@ for interacting with an API. For example:
     from gcloud import datastore
     client = datastore.Client()
 
-Passing no arguments at all will "just work" if you've following the
+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`_.
 
@@ -50,38 +50,105 @@ Credential Discovery Precedence
 -------------------------------
 
 When loading the `Application Default Credentials`_, the library will check
-properties of your local environment in the following order
+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, if your code will only run in one place, you may want to
+use an explicit set of credentials suited to your environment.
+Or, you may want to use two separate accounts
+to simultaneously access data from different projects.
+
+After creating a
+:class:`Credentials <oauth2client.client.Credentials>` object specific to
+your environment, 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
+    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 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()