DOC: update the DataFrame.pivot	docstring
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.pivot) ######################
################################################################################

Return reshaped DataFrame summarized by given index / column values.

Reshape data (produce a "pivot" table) based on column values. Uses
unique values from index / columns to form axes of the resulting
DataFrame. This function does not support data aggregation, multiple
values will result in hierarchically indexed columns.

Parameters
----------
index : string or object, optional
    Column name to use to make new frame's index. If None, uses
    existing index.
columns : string or object, optional
    Column name to use to make new frame's columns.
values : string or object, optional
    Column name to use for populating new frame's values. If not
    specified, all remaining columns will be used and the result will
    have hierarchically indexed columns.

Returns
-------
DataFrame
    Returns reshaped DataFrame.

See Also
--------
DataFrame.pivot_table : generalization of pivot that can handle
    duplicate values for one index/column pair
DataFrame.unstack : pivot based on the index values instead of a
    column

Notes
-----
For finer-tuned control, see hierarchical indexing documentation along
with the related stack/unstack methods

Examples
--------

>>> df = pd.DataFrame({'foo': ['one','one','one','two','two','two'],
...                    'bar': ['A', 'B', 'C', 'A', 'B', 'C'],
...                    'baz': [1, 2, 3, 4, 5, 6]})
>>> df
    foo   bar  baz
0   one   A    1
1   one   B    2
2   one   C    3
3   two   A    4
4   two   B    5
5   two   C    6

>>> df.pivot(index='foo', columns='bar', values='baz')
bar  A   B   C
foo
one  1   2   3
two  4   5   6

>>> df.pivot(index='foo', columns='bar')['baz']
bar  A   B   C
foo
one  1   2   3
two  4   5   6

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.DataFrame.pivot" correct. :)
```

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.
