DOC: Explain pivot vs. pivot_table (#6950) (#14650)

Move pivot paragraph to pivot table section

add pivot_table reference to pivot

Author: mroeschke

doc/source/reshaping.rst

@@ -323,6 +323,10 @@ Pivot tables
 
 .. _reshaping.pivot:
 
+While ``pivot`` provides general purpose pivoting of DataFrames with various
+data types (strings, numerics, etc.), Pandas also provides the ``pivot_table``
+function for pivoting with aggregation of numeric data.
+
 The function ``pandas.pivot_table`` can be used to create spreadsheet-style pivot
 tables. See the :ref:`cookbook<cookbook.pivot>` for some advanced strategies
 

pandas/core/reshape.py

@@ -357,6 +357,11 @@ def pivot_simple(index, columns, values):
     Returns
     -------
     DataFrame
+
+    See also
+    --------
+    DataFrame.pivot_table : generalization of pivot that can handle
+        duplicate values for one index/column pair
     """
     if (len(index) != len(columns)) or (len(columns) != len(values)):
         raise AssertionError('Length of index, columns, and values must be the'

pandas/tools/pivot.py

@@ -75,6 +75,11 @@ def pivot_table(data, values=None, index=None, columns=None, aggfunc='mean',
     Returns
     -------
     table : DataFrame
+
+    See also
+    --------
+    DataFrame.pivot : pivot without aggregation that can handle
+        non-numeric data
     """
     index = _convert_by(index)
     columns = _convert_by(columns)