diff --git a/docs/source/conf.py b/docs/source/conf.py
index 3dfd9f86..3ad2767f 100644
--- a/docs/source/conf.py
+++ b/docs/source/conf.py
@@ -359,8 +359,12 @@
# texinfo_no_detailmenu = False
-# Example configuration for intersphinx: refer to the Python standard library.
-intersphinx_mapping = {'https://docs.python.org/': None}
+# Configuration for intersphinx:
+intersphinx_mapping = {
+ 'https://docs.python.org/': None,
+ 'https://pandas.pydata.org/pandas-docs/stable/': None,
+ 'https://google-auth.readthedocs.io/en/latest/': None,
+}
extlinks = {'issue': ('https://github.com/pydata/pandas-gbq/issues/%s',
'GH#'),
diff --git a/docs/source/howto/authentication.rst b/docs/source/howto/authentication.rst
new file mode 100644
index 00000000..9f69ed12
--- /dev/null
+++ b/docs/source/howto/authentication.rst
@@ -0,0 +1,62 @@
+Authentication
+==============
+
+pandas-gbq `authenticates with the Google BigQuery service
+`_ via OAuth 2.0.
+
+.. _authentication:
+
+
+Authentication with a Service Account
+--------------------------------------
+
+Using service account credentials is particularly useful when working on
+remote servers without access to user input.
+
+Create a service account key via the `service account key creation page
+`_ in
+the Google Cloud Platform Console. Select the JSON key type and download the
+key file.
+
+To use service account credentials, set the ``private_key`` parameter to one
+of:
+
+* A file path to the JSON file.
+* A string containing the JSON file contents.
+
+See the `Getting started with authentication on Google Cloud Platform
+`_ guide for
+more information on service accounts.
+
+Default Authentication Methods
+------------------------------
+
+If the ``private_key`` parameter is ``None``, pandas-gbq tries the following
+authentication methods:
+
+1. Application Default Credentials via the :func:`google.auth.default`
+ function.
+
+ .. note::
+
+ If pandas-gbq can obtain default credentials but those credentials
+ cannot be used to query BigQuery, pandas-gbq will also try obtaining
+ user account credentials.
+
+ A common problem with default credentials when running on Google
+ Compute Engine is that the VM does not have sufficient scopes to query
+ BigQuery.
+
+2. User account credentials.
+
+ pandas-gbq loads cached credentials from a hidden user folder on the
+ operating system. Override the location of the cached user credentials
+ by setting the ``PANDAS_GBQ_CREDENTIALS_FILE`` environment variable.
+
+ If pandas-gbq does not find cached credentials, it opens a browser window
+ asking for you to authenticate to your BigQuery account using the product
+ name ``pandas GBQ``.
+
+ Additional information on the user credentails authentication mechanism
+ can be found `here
+ `__.
diff --git a/docs/source/index.rst b/docs/source/index.rst
index 44a61843..8e895145 100644
--- a/docs/source/index.rst
+++ b/docs/source/index.rst
@@ -26,6 +26,7 @@ Contents:
install.rst
intro.rst
+ howto/authentication.rst
reading.rst
writing.rst
tables.rst
diff --git a/docs/source/intro.rst b/docs/source/intro.rst
index 0cad9ae8..a7ec65c7 100644
--- a/docs/source/intro.rst
+++ b/docs/source/intro.rst
@@ -41,42 +41,3 @@ more verbose logs, you can do something like:
logger = logging.getLogger('pandas_gbq')
logger.setLevel(logging.DEBUG)
logger.addHandler(logging.StreamHandler(stream=sys.stdout))
-
-
-.. _authentication:
-
-Authentication
-''''''''''''''
-
-Authentication to the Google ``BigQuery`` service via ``OAuth 2.0``
-is possible with either user or service account credentials.
-
-Authentication via user account credentials is as simple as following the prompts in a browser window
-which will automatically open for you. You authenticate to the specified
-``BigQuery`` account using the product name ``pandas GBQ``.
-The remote authentication is supported via the ``auth_local_webserver`` in ``read_gbq``. By default,
-account credentials are stored in an application-specific hidden user folder on the operating system. You
-can override the default credentials location via the ``PANDAS_GBQ_CREDENTIALS_FILE`` environment variable.
-Additional information on the authentication mechanism can be found
-`here `__.
-
-Authentication via service account credentials is possible through the `'private_key'` parameter. This method
-is particularly useful when working on remote servers (eg. Jupyter Notebooks on remote host).
-Additional information on service accounts can be found
-`here `__.
-
-Authentication via ``application default credentials`` is also possible, but only valid
-if the parameter ``private_key`` is not provided. This method requires that the
-credentials can be fetched from the development environment. Otherwise, the OAuth2
-client-side authentication is used. Additional information can be found on
-`application default credentials `__.
-
-.. note::
-
- The `'private_key'` parameter can be set to either the file path of the service account key
- in JSON format, or key contents of the service account key in JSON format.
-
-.. note::
-
- A private key can be obtained from the Google developers console by clicking
- `here `__. Use JSON key type.
diff --git a/pandas_gbq/gbq.py b/pandas_gbq/gbq.py
index 0a14c7b1..5fb53bba 100644
--- a/pandas_gbq/gbq.py
+++ b/pandas_gbq/gbq.py
@@ -476,23 +476,12 @@ def read_gbq(query, project_id=None, index_col=None, col_order=None,
The main method a user calls to execute a Query in Google BigQuery
and read results into a pandas DataFrame.
- The Google Cloud library is used.
- Documentation is available `here
- `__
+ This method uses the Google Cloud client library to make requests to
+ Google BigQuery, documented `here
+ `__.
- Authentication to the Google BigQuery service is via OAuth 2.0.
-
- - If "private_key" is not provided:
-
- By default "application default credentials" are used.
-
- If default application credentials are not found or are restrictive,
- user account credentials are used. In this case, you will be asked to
- grant permissions for product name 'pandas GBQ'.
-
- - If "private_key" is provided:
-
- Service account credentials will be used to authenticate.
+ See the :ref:`How to authenticate with Google BigQuery `
+ guide for authentication instructions.
Parameters
----------
@@ -612,29 +601,18 @@ def to_gbq(dataframe, destination_table, project_id=None, chunksize=None,
The main method a user calls to export pandas DataFrame contents to
Google BigQuery table.
- Google BigQuery API Client Library v2 for Python is used.
- Documentation is available `here
- `__
-
- Authentication to the Google BigQuery service is via OAuth 2.0.
-
- - If "private_key" is not provided:
-
- By default "application default credentials" are used.
-
- If default application credentials are not found or are restrictive,
- user account credentials are used. In this case, you will be asked to
- grant permissions for product name 'pandas GBQ'.
-
- - If "private_key" is provided:
+ This method uses the Google Cloud client library to make requests to
+ Google BigQuery, documented `here
+ `__.
- Service account credentials will be used to authenticate.
+ See the :ref:`How to authenticate with Google BigQuery `
+ guide for authentication instructions.
Parameters
----------
- dataframe : DataFrame
+ dataframe : pandas.DataFrame
DataFrame to be written
- destination_table : string
+ destination_table : str
Name of table to be written, in the form 'dataset.tablename'
project_id : str (optional when available in environment)
Google BigQuery Account project ID.