DOC: Fix docstring for read_sql_table
State: closed

- [ ] closes #xxxx
- [ ] tests added / passed
- [X] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

```
################################################################################
###################### Docstring (pandas.read_sql_table)  ######################
################################################################################

Read SQL database table into a DataFrame.

Given a table name and a SQLAlchemy connectable, returns a DataFrame.
This function does not support DBAPI connections.

Parameters
----------
table_name : str
    Name of SQL table in database.
con : SQLAlchemy connectable or database URI str
    SQLite DBAPI connection mode not supported.
schema : str, default None
    Name of SQL schema in database to query (if database flavor
    supports this). Uses default schema if None (default).
index_col : str or list of str, optional, default: None
    Column(s) to set as index(MultiIndex).
coerce_float : bool, default True
    Attempts to convert values of non-string, non-numeric objects (like
    decimal.Decimal) to floating point. Can result in loss of Precision.
parse_dates : list or dict, default None
    The behavior is as follows:
    - List of column names to parse as dates.
    - Dict of ``{column_name: format string}`` where format string is
      strftime compatible in case of parsing string times or is one of
      (D, s, ns, ms, us) in case of parsing integer timestamps.
    - Dict of ``{column_name: arg dict}``, where the arg dict corresponds
      to the keyword arguments of :func:`pandas.to_datetime`
      Especially useful with databases without native Datetime support,
      such as SQLite.
columns : list, default None
    List of column names to select from SQL table.
chunksize : int, default None
    If specified, returns an iterator where `chunksize` is the number of
    rows to include in each chunk.

Returns
-------
DataFrame
    A SQL table is returned as two-dimensional data structure with labeled
    axes.

See Also
--------
read_sql_query : Read SQL query into a DataFrame.
read_sql : Read SQL query or database table into a DataFrame.

Notes
-----
Any datetime values with time zone information will be converted to UTC.

Examples
--------
>>> pd.read_sql_table('table_name', 'postgres:///db_name')  # doctest:+SKIP

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.read_sql_table" correct. :)
```

Labels:
name: Docs
name: Code Style
description: Code style, linting, code_checks

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25465?src=pr&el=h1) Report
> Merging [#25465](https://codecov.io/gh/pandas-dev/pandas/pull/25465?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/fe1654faa86836a0007bb513504e57c5c9935b8b?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

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

```diff
@@           Coverage Diff           @@
##           master   #25465   +/-   ##
=======================================
  Coverage   91.74%   91.74%           
=======================================
  Files         173      173           
  Lines       52923    52923           
=======================================
  Hits        48554    48554           
  Misses       4369     4369
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.31% <ø> (ø)` | :arrow_up: |
| #single | `41.73% <ø> (ø)` | :arrow_up: |


------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25465?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/25465?src=pr&el=footer). Last update [fe1654f...34fcf5c](https://codecov.io/gh/pandas-dev/pandas/pull/25465?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25465?src=pr&el=h1) Report
> Merging [#25465](https://codecov.io/gh/pandas-dev/pandas/pull/25465?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/e9de5f3e159296a46bc62aa42a6225b67d8a4f10?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

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

```diff
@@           Coverage Diff           @@
##           master   #25465   +/-   ##
=======================================
  Coverage   91.75%   91.75%           
=======================================
  Files         173      173           
  Lines       52947    52947           
=======================================
  Hits        48581    48581           
  Misses       4366     4366
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.31% <ø> (ø)` | :arrow_up: |
| #single | `41.72% <ø> (ø)` | :arrow_up: |


------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/25465?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/25465?src=pr&el=footer). Last update [e9de5f3...f114512](https://codecov.io/gh/pandas-dev/pandas/pull/25465?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

@igblackadder : This looks great!  Can you merge / rebase your branch with the most recent `master` ?  That will fix the test failures.

@datapythonista : Don't we have to add this file for its docstrings to get linted, or are there other docstring issues that still need to be addressed in `pandas/io/sql.py` ?
@gfyoung might be something I'm overlooking but I think the validation runs for all docstrings but a subset of codes

https://github.com/pandas-dev/pandas/blob/c9863865c217867583e8f6592ba88d9200601992/ci/code_checks.sh#L245

@gfyoung, what @WillAyd said is correct. For now we're still focussing on getting as many formatting errors fixed for all docstrings. After we've got everything that is pure formatting (capitalization, missing full stop...), we'll probably switch to have some groups of docstrings (e.g. `pandas.Series.*`) fully validated.
Looks like all comments have been addressed, so merging.
Thanks @igblackadder !
Thank you @gfyoung and @WillAyd for your helpful comments. @datapythonista thank you so much for time and insight on Wednesday and for your comments on this PR!