DOC: Explain pivot vs. pivot_table (#6950)

Author: mroeschke

doc/source/reshaping.rst

@@ -90,6 +90,11 @@ You of course can then select subsets from the pivoted DataFrame:
 Note that this returns a view on the underlying data in the case where the data
 are homogeneously-typed.
 
+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 (see the
+section on :ref:`pivot tables<reshaping.pivot>`).
+
 .. _reshaping.stacking:
 
 Reshaping by stacking and unstacking

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)