DOC: update the DataFrame.pivot docstring (#20250)

* DOC: DataFrame.pivot

* DOC: grammar

* Fixing pivot

* Added Raises and example

* Say what to do

* Refer to user guide

* Fixed name

Author: amuta

pandas/core/frame.py

@@ -4456,44 +4456,55 @@ def last_valid_index(self):
 
     def pivot(self, index=None, columns=None, values=None):
         """
+        Return reshaped DataFrame organized 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.
+        unique values from specified `index` / `columns` to form axes of the resulting
+        DataFrame. This function does not support data aggregation, multiple
+        values will result in a MultiIndex in the columns. See the
+        :ref:`User Guide <reshaping>` for more on reshaping.
 
         Parameters
         ----------
         index : string or object, optional
-            Column name to use to make new frame's index. If None, uses
+            Column to use to make new frame's index. If None, uses
             existing index.
         columns : string or object
-            Column name to use to make new frame's columns
+            Column 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
+            Column 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
+            have hierarchically indexed columns.
 
         Returns
         -------
-        pivoted : DataFrame
+        DataFrame
+            Returns reshaped DataFrame.
 
-        See also
+        Raises
+        ------
+        ValueError:
+            When there are any `index`, `columns` combinations with multiple
+            values. `DataFrame.pivot_table` when you need to aggregate.
+
+        See Also
         --------
         DataFrame.pivot_table : generalization of pivot that can handle
-            duplicate values for one index/column pair
+            duplicate values for one index/column pair.
         DataFrame.unstack : pivot based on the index values instead of a
-            column
+            column.
 
         Notes
         -----
         For finer-tuned control, see hierarchical indexing documentation along
-        with the related stack/unstack methods
+        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 = 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
@@ -4504,16 +4515,36 @@ def pivot(self, index=None, columns=None, values=None):
         5   two   C    6
 
         >>> df.pivot(index='foo', columns='bar', values='baz')
-             A   B   C
+        bar  A   B   C
+        foo
         one  1   2   3
         two  4   5   6
 
         >>> df.pivot(index='foo', columns='bar')['baz']
-             A   B   C
+        bar  A   B   C
+        foo
         one  1   2   3
         two  4   5   6
 
+        A ValueError is raised if there are any duplicates.
+
+        >>> df = pd.DataFrame({"foo": ['one', 'one', 'two', 'two'],
+        ...                    "bar": ['A', 'A', 'B', 'C'],
+        ...                    "baz": [1, 2, 3, 4]})
+        >>> df
+           foo bar  baz
+        0  one   A    1
+        1  one   A    2
+        2  two   B    3
+        3  two   C    4
+
+        Notice that the first two rows are the same for our `index`
+        and `columns` arguments.
 
+        >>> df.pivot(index='foo', columns='bar', values='baz')
+        Traceback (most recent call last):
+           ...
+        ValueError: Index contains duplicate entries, cannot reshape
         """
         from pandas.core.reshape.reshape import pivot
         return pivot(self, index=index, columns=columns, values=values)