Update docs about credentials (#609)

Author: jdangerx

docs/source/index.rst

@@ -99,19 +99,33 @@ Several modes of authentication are supported:
       or container engine) and fetch the credentials automatically from the
       metadata service.
 
-    - if ``token=dict(...)`` or ``token=<filepath>``, you may supply a token generated by the
-      gcloud_ utility; this is either a python dictionary, or the name of a file
-      containing the JSON returned by logging in with the gcloud CLI tool (e.g.,
-      ``~/.config/gcloud/application_default_credentials.json`` or
-      ``~/.config/gcloud/legacy_credentials/<YOUR GOOGLE USERNAME>/adc.json``)
-      or any value google ``Credentials`` object.
+    - if ``token=dict(...)`` or ``token=<filepath>``, you may supply a token
+      generated by the gcloud_ utility. This can be
+
+      - a python dictionary
+
+      - the path to a file containing the JSON returned by logging in with the
+        gcloud CLI tool (e.g.,
+        ``~/.config/gcloud/application_default_credentials.json`` or
+        ``~/.config/gcloud/legacy_credentials/<YOUR GOOGLE
+        USERNAME>/adc.json``)
+
+      - the path to a service account key
+
+      - a google.auth.credentials.Credentials_ object
+
+      Note that ``~`` will not be automatically expanded to the user home
+      directory, and must be manually expanded with a utility like
+      ``os.path.expanduser()``.
 
     - you can also generate tokens via Oauth2 in the browser using ``token='browser'``,
       which gcsfs then caches in a special file, ~/.gcs_tokens, and can subsequently be accessed with ``token='cache'``.
 
     - anonymous only access can be selected using ``token='anon'``, e.g. to access
       public resources such as 'anaconda-public-data'.
 
+.. _google.auth.credentials.Credentials: https://google-auth.readthedocs.io/en/master/reference/google.auth.credentials.html#google.auth.credentials.Credentials
+
 The acquired session tokens are *not* preserved when serializing the instances, so
 it is safe to pass them to worker processes on other machines if using in a
 distributed computation context. If credentials are given by a file path, however,