ENH/DOC: update pandas-gbq signature and docstring
State: closed

Delegates more of the behavior and documentation for `to_gbq` and
`read_gbq` methods to the `pandas-gbq` library. This duplicate
documentation was getting out of sync.


Please include the output of the validation script below between the "```" ticks:

```
$ scripts/validate_docstrings.py pandas.DataFrame.to_gbq

################################################################################
##################### Docstring (pandas.DataFrame.to_gbq)  #####################
################################################################################

Write a DataFrame to a Google BigQuery table.

This function requires the `pandas-gbq package
<https://pandas-gbq.readthedocs.io>`__.

See: :meth:`pandas_gbq.to_gbq`

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
	No returns section found
	See Also section not found
	No examples section found
(3.6.2/envs/pandas-dev)
# swast @ swast-macbookpro2 in ~/src/pandas/pandas on git:master o [16:56:32] C:5
$ scripts/validate_docstrings.py pandas.io.gbq.read_gbq

################################################################################
###################### Docstring (pandas.io.gbq.read_gbq) ######################
################################################################################

Load data from Google BigQuery.

This function requires the `pandas-gbq package
<https://pandas-gbq.readthedocs.io>`__.

See :meth:`pandas_gbq.read_gbq`.

Returns
-------
df: DataFrame
    DataFrame representing results of query

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs', 'args'} not documented
	See Also section not found
	No examples section found
(3.6.2/envs/pandas-dev)
# swast @ swast-macbookpro2 in ~/src/pandas/pandas on git:master o [16:56:39] C:4
$ scripts/validate_docstrings.py pandas.DataFrame.to_gbq

################################################################################
##################### Docstring (pandas.DataFrame.to_gbq)  #####################
################################################################################

Write a DataFrame to a Google BigQuery table.

This function requires the `pandas-gbq package
<https://pandas-gbq.readthedocs.io>`__.

See: :meth:`pandas_gbq.to_gbq`

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'args', 'kwargs'} not documented
	No returns section found
	See Also section not found
	No examples section found
```

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

**Validation script gives errors** This PR removes documentation which is duplicated in the `pandas-gbq` docs and add intersphinx links to the relevant methods.

Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] whatsnew entry


Labels:
name: Docs

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=h1) Report
> Merging [#20564](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/6d610a4d9393c0d0335267dc3252ccabb9e51e43?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `50%`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20564/graphs/tree.svg?token=eZ4WkYLtcO&src=pr&height=150&width=650)](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=tree)

```diff
@@            Coverage Diff             @@
##           master   #20564      +/-   ##
==========================================
- Coverage   91.82%   91.81%   -0.01%     
==========================================
  Files         153      153              
  Lines       49256    49265       +9     
==========================================
+ Hits        45227    45235       +8     
- Misses       4029     4030       +1
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.2% <50%> (-0.01%)` | :arrow_down: |
| #single | `41.9% <50%> (-0.01%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/20564/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `25% <50%> (ø)` | :arrow_up: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20564/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.15% <50%> (ø)` | :arrow_up: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20564/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.39% <0%> (-0.12%)` | :arrow_down: |
| [pandas/util/\_test\_decorators.py](https://codecov.io/gh/pandas-dev/pandas/pull/20564/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvX3Rlc3RfZGVjb3JhdG9ycy5weQ==) | `92% <0%> (+0.1%)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20564/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `84.73% <0%> (+0.2%)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=footer). Last update [6d610a4...1ab0934](https://codecov.io/gh/pandas-dev/pandas/pull/20564?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

can we just update the signature (of course can have the link as well). It just provides nice tab completeion and doc-strings if its in-line.
Hello @tswast! Thanks for updating the PR.







Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on April 09, 2018 at 08:39 Hours UTC
@jreback Good point. I've updated the PR to just add the links to the `pandas-gbq` docs and do some light clean-ups based on `scripts/validate_docstrings.py` warnings.

I've built the docs locally and verified that the intersphinx links in the See Also section do render correctly.
@jreback Was this what you meant? I've reverted the function signatures back to the original (but added `**kwargs` for some new args added in newer versions of `pandas-gbq`).
I've addressed the comments and CI is now passing again. Is there anything left to do on this PR?
can u add a note in whatsnew (documentation section is ok)
otherwise lgtm 
Okay. Added to whatsnew. (And made a couple tweaks for recently released of Pandas-GBQ)
@tswast Thanks!
Thanks @jorisvandenbossche 🎉 
can/should we remove "verbose"?
> can/should we remove "verbose"?

It hasn't had any effect in pandas-gbq since 2018-04-03. Makes sense to remove in 1.0.
@tswast great, thanks.  how about `private_key`?
I'm a little more hesitant on `private_key`, as I never actually removed the code for it in pandas-gbq. Filed https://github.com/pydata/pandas-gbq/issues/301 to start throwing.