Update doc strings, pd.Panel is deprecated (#18956)

pandas/core/frame.py

@@ -1403,6 +1403,8 @@ def to_panel(self):
         Transform long (stacked) format (DataFrame) into wide (3D, Panel)
         format.
 
+        .. deprecated:: 0.20.0
+
         Currently the index of the DataFrame must be a 2-level MultiIndex. This
         may be generalized later
 

pandas/core/panel.py

@@ -111,6 +111,13 @@ class Panel(NDFrame):
     """
     Represents wide format panel data, stored as 3-dimensional array
 
+   .. deprecated:: 0.20.0
+       The recommended way to represent 3-D data are with a MultiIndex on a
+       DataFrame via the :attr:`~Panel.to_frame()` method or with the
+       `xarray package <http://xarray.pydata.org/en/stable/>`__.
+       Pandas provides a :attr:`~Panel.to_xarray()` method to automate this
+       conversion.
+
     Parameters
     ----------
     data : ndarray (items x major x minor), or dict of DataFrames