DOC: render BigQuery auth flows as links

Also, adjust line breaks per review comments.

Author: tswast

pandas/core/frame.py

@@ -1116,10 +1116,9 @@ def to_dict(self, orient='dict', into=dict):
         else:
             raise ValueError("orient '%s' not understood" % orient)
 
-    def to_gbq(
-            self, destination_table, project_id, chunksize=10000,
-            verbose=True, reauth=False, if_exists='fail', private_key=None,
-            auth_local_webserver=False, table_schema=None):
+    def to_gbq(self, destination_table, project_id, chunksize=None,
+               verbose=True, reauth=False, if_exists='fail', private_key=None,
+               auth_local_webserver=False, table_schema=None):
         """
         Write a DataFrame to a Google BigQuery table.
 
@@ -1128,57 +1127,61 @@ def to_gbq(
 
         Authentication to the Google BigQuery service is via OAuth 2.0.
 
-        - If "private_key" is not provided:
+        - If ``private_key`` is provided, the library loads the JSON service
+          account credentials and uses those to authenticate.
 
-          By default "application default credentials" are used.
+        - If no ``private_key`` is provided, the library tries `application
+          default credentials`_.
 
-          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'.
+          .. _application default credentials:
+              https://cloud.google.com/docs/authentication/production#providing_credentials_to_your_application
 
-        - If "private_key" is provided:
-
-          Service account credentials will be used to authenticate.
+        - If application default credentials are not found or cannot be used
+          with BigQuery, the library authenticates with user account
+          credentials. In this case, you will be asked to grant permissions
+          for product name 'pandas GBQ'.
 
         Parameters
         ----------
-        dataframe : DataFrame
-            DataFrame to be written to Google BigQuery.
-        destination_table : string
+        destination_table : str
             Name of table to be written, in the form 'dataset.tablename'.
         project_id : str
             Google BigQuery Account project ID.
-        chunksize : int (default 10000)
+        chunksize : int, optional
             Number of rows to be inserted in each chunk from the dataframe.
             Set to ``None`` to load the whole dataframe at once.
-        verbose : boolean (default True)
+        verbose : bool, default True
             Show percentage complete.
-        reauth : boolean (default False)
+        reauth : bool, default False
             Force Google BigQuery to reauthenticate the user. This is useful
             if multiple accounts are used.
-        if_exists : {'fail', 'replace', 'append'}, default 'fail'
-            Behavior when the destination table exists.
-            'fail': If table exists, do nothing.
-            'replace': If table exists, drop it, recreate it, and insert data.
-            'append': If table exists, insert data. Create if does not exist.
-        private_key : str (optional)
+        if_exists : str, default 'fail'
+            Behavior when the destination table exists. Value can be one of:
+
+            ``'fail'``
+                If table exists, do nothing.
+            ``'replace'``
+                If table exists, drop it, recreate it, and insert data.
+            ``'append'``
+                If table exists, insert data. Create if does not exist.
+        private_key : str, optional
             Service account private key in JSON format. Can be file path
             or string contents. This is useful for remote server
             authentication (eg. Jupyter/IPython notebook on remote host).
-        auth_local_webserver : boolean (default False)
-            Use the [local webserver flow] instead of the [console flow]
+        auth_local_webserver : bool, default False
+            Use the `local webserver flow`_ instead of the `console flow`_
             when getting user credentials.
 
-            .. [local webserver flow]
+            .. _local webserver flow:
                 http://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_local_server
-            .. [console flow]
+            .. _console flow:
                 http://google-auth-oauthlib.readthedocs.io/en/latest/reference/google_auth_oauthlib.flow.html#google_auth_oauthlib.flow.InstalledAppFlow.run_console
 
             *New in version 0.2.0 of pandas-gbq*.
-        table_schema : list of dicts (optional)
+        table_schema : list of dicts, optional
             List of BigQuery table fields to which according DataFrame
-            columns conform to, e.g. `[{'name': 'col1', 'type':
-            'STRING'},...]`. If schema is not provided, it will be
+            columns conform to, e.g. ``[{'name': 'col1', 'type':
+            'STRING'},...]``. If schema is not provided, it will be
             generated according to dtypes of DataFrame columns. See
             BigQuery API documentation on available names of a field.
 

pandas/io/gbq.py

@@ -21,9 +21,9 @@ def _try_import():
     return pandas_gbq
 
 
-def read_gbq(
-        query, project_id=None, index_col=None, col_order=None, reauth=False,
-        verbose=True, private_key=None, dialect='legacy', **kwargs):
+def read_gbq(query, project_id=None, index_col=None, col_order=None,
+             reauth=False, verbose=True, private_key=None, dialect='legacy',
+             **kwargs):
     """
     Load data from Google BigQuery.
 
@@ -101,10 +101,9 @@ def read_gbq(
         **kwargs)
 
 
-def to_gbq(
-        dataframe, destination_table, project_id, chunksize=10000,
-        verbose=True, reauth=False, if_exists='fail', private_key=None,
-        auth_local_webserver=False, table_schema=None):
+def to_gbq(dataframe, destination_table, project_id, chunksize=None,
+           verbose=True, reauth=False, if_exists='fail', private_key=None,
+           auth_local_webserver=False, table_schema=None):
     pandas_gbq = _try_import()
     return pandas_gbq.to_gbq(
         dataframe, destination_table, project_id, chunksize=chunksize,