DOC: update the DataFrame.to_hdf() docstirng
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X] PR title is "DOC: update the <your-function-or-method> docstring"
- [X] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
##################### Docstring (pandas.DataFrame.to_hdf)  #####################
################################################################################

Write the contained data to an HDF5 file using HDFStore.

Hierarchical Data Format (HDF) is self-describing, allowing an
application to interpret the structure and contents of a file with
no outside information. One HDF file can hold a mix of related objects
which can be accessed as a group or as individual objects.

In order to add another :class:`~pandas.DataFrame` or
:class:`~pandas.Series` to an existing HDF file please use append mode
and different a key.

Parameters
----------
path_or_buf : str or pandas.HDFStore
    File path or HDFStore object.
key : str
    Identifier for the group in the store.
mode : {'a', 'w', 'r+'}, default is 'a'
    Mode to open file:
        - ``'w'``: write, a new file is created (an existing file with
            the same name would be deleted).
        - ``'a'``: append, an existing file is opened for reading and
            writing, and if the file does not exist it is created.
        - `'r+'`: similar to ``'a'``, but the file must already exist.
format : {'fixed', 'table'}, default is 'fixed'
    Possible values:
        - fixed: Fixed format. Fast writing/reading. Not-appendable,
            nor searchable.
        - table: Table format. Write as a PyTables Table structure
            which may perform worse but allow more flexible operations
            like searching / selecting subsets of the data.
append : boolean, default False
    For Table formats, append the input data to the existing.
data_columns :  list of columns or True, optional
    List of columns to create as indexed data columns for on-disk
    queries, or True to use all columns. By default only the axes
    of the object are indexed. See `here
    <http://pandas.pydata.org/pandas-docs/stable/io.html#query-via-data-columns>`__.
    Applicable only to format='table'.
complevel : {0-9}, optional
    Specifies a compression level for data.
    A value of 0 disables compression.
complib : {'zlib', 'lzo', 'bzip2', 'blosc'}, default 'zlib'
    Specifies the compression library to be used.
    As of v0.20.2 these additional compressors for Blosc are supported
    (default if no compressor specified: 'blosc:blosclz'):
    {'blosc:blosclz', 'blosc:lz4', 'blosc:lz4hc', 'blosc:snappy',
    'blosc:zlib', 'blosc:zstd'}.
    Specifying a compression library which is not available issues
    a ValueError.
fletcher32 : bool, default False
    If applying compression use the fletcher32 checksum.
dropna : bool, default False
    If true, ALL nan rows will not be written to store.

See Also
--------
DataFrame.to_csv : write out to a csv file.
DataFrame.to_sql : write to a sql table.
DataFrame.to_feather : write out feather-format for DataFrames.

Examples
--------
>>> df = pd.DataFrame({'A': [1, 2, 3], 'B': [4, 5, 6]},
...                   index=['a', 'b', 'c'])
>>> df.to_hdf('data.h5', key='df', mode='w')

We can append another object to the same file:

>>> s = pd.Series([1, 2, 3, 4])
>>> s.to_hdf('data.h5', key='s')

Reading from HDF file:

>>> pd.read_hdf('data.h5', 'df')
A  B
a  1  4
b  2  5
c  3  6
>>> pd.read_hdf('data.h5', 's')
0    1
1    2
2    3
3    4
dtype: int64

Notes
-----
Learn more about `Hierarchical Data Format (HDF)
<https://support.hdfgroup.org/HDF5/whatishdf5.html>`__.

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
	Errors in parameters section
		Parameters {'kwargs'} not documented
		Unknown parameters {'format', 'complevel', 'mode', 'append', 'complib', 'dropna', 'data_columns', 'fletcher32'}
	No returns 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.

- **kwargs are actually misleading and should be put as args, will do it in separate pull request.
- returns None


Checklist for other PRs (remove this part if you are doing a PR for the pandas documentation sprint):

- [ ] closes #xxxx
- [ ] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Labels:
name: Docs
name: IO HDF5
description: read_hdf, HDFStore

Comments:
Hello @acidburnburn! Thanks for updating the PR.

 - In the file [`pandas/core/generic.py`](https://github.com/pandas-dev/pandas/blob/eebfc397c9bbb71f43f9696f86c1b9d7264fdef0/pandas/core/generic.py), following are the PEP8 issues :

> [Line 1810:1](https://github.com/pandas-dev/pandas/blob/eebfc397c9bbb71f43f9696f86c1b9d7264fdef0/pandas/core/generic.py#L1810): [W293](https://duckduckgo.com/?q=pep8%20W293) blank line contains whitespace
> [Line 1818:1](https://github.com/pandas-dev/pandas/blob/eebfc397c9bbb71f43f9696f86c1b9d7264fdef0/pandas/core/generic.py#L1818): [W293](https://duckduckgo.com/?q=pep8%20W293) blank line contains whitespace



##### Comment last updated on March 22, 2018 at 09:13 Hours UTC
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20186?src=pr&el=h1) Report
> Merging [#20186](https://codecov.io/gh/pandas-dev/pandas/pull/20186?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/7273ea0709590e6264607f227bb8def0ef656c50?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #20186      +/-   ##
==========================================
- Coverage   91.77%   91.77%   -0.01%     
==========================================
  Files         152      152              
  Lines       49205    49215      +10     
==========================================
+ Hits        45159    45167       +8     
- Misses       4046     4048       +2
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.16% <100%> (-0.01%)` | :arrow_down: |
| #single | `41.84% <14.28%> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20186?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20186/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.85% <100%> (ø)` | :arrow_up: |
| [pandas/util/testing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20186/diff?src=pr&el=tree#diff-cGFuZGFzL3V0aWwvdGVzdGluZy5weQ==) | `83.91% <0%> (-0.05%)` | :arrow_down: |
| [pandas/core/window.py](https://codecov.io/gh/pandas-dev/pandas/pull/20186/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvd2luZG93LnB5) | `96.26% <0%> (-0.01%)` | :arrow_down: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20186/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.27% <0%> (ø)` | :arrow_up: |
| [pandas/io/json/normalize.py](https://codecov.io/gh/pandas-dev/pandas/pull/20186/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2pzb24vbm9ybWFsaXplLnB5) | `96.93% <0%> (+0.06%)` | :arrow_up: |

------

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

Thanks @acidburnburn !