add deprecate_panel section to docs

Author: jreback

doc/source/dsintro.rst

@@ -766,10 +766,7 @@ Panel
 .. warning::
 
     In 0.20.0, ``Panel`` is deprecated and will be removed in
-    a future version. The recommended way to represent 3-D data are
-    with a ``MultiIndex``on a ``DataFrame`` via the :meth:`~Panel.to_frame` or
-    with the `xarray package <http://xarray.pydata.org/en/stable/>`__. Pandas
-    provides a :meth:`~Panel.to_xarray` method to automate this conversion.
+    a future version. See the section :ref:`Deprecate Panel <dsintro.deprecate_panel>`.
 
 Panel is a somewhat less-used, but still important container for 3-dimensional
 data. The term `panel data <http://en.wikipedia.org/wiki/Panel_data>`__ is
@@ -937,6 +934,46 @@ method:
                     minor_axis=['a', 'b', 'c', 'd'])
    panel.to_frame()
 
+
+.. _dsintro.deprecate_panel:
+
+Deprecate Panel
+---------------
+
+Over the last few years, pandas has increased in both breadth and depth, with new features,
+datatype support, and manipulation routines. As a result, supporting efficient indexing and functional
+routines for ``Series``, ``DataFrame`` and ``Panel`` has contributed to an increasingly fragmented and
+difficult-to-understand codebase.
+
+The 3-d structure of a ``Panel`` is much less common for many types of data analysis,
+than the 1-d of the ``Series`` or the 2-D of the ``DataFrame``. Going forward it makes sense for
+pandas to focus on these areas exclusively.
+
+Oftentimes, one can simply use a MultiIndex ``DataFrame`` for easily working with higher dimensional data.
+
+In additon, the ``xarray`` package was built from the ground up, specifically in order to
+support the multi-dimensional analysis that is one of ``Panel`` s main usecases.
+
+.. ipython:: python
+   :okwarning:
+
+   p = tm.makePanel()
+   p
+
+Convert to a MultiIndex DataFrame
+
+.. ipython:: python
+
+   p.to_frame()
+
+Alternatively, one can convert to an xarray ``DataArray``.
+
+.. ipython:: python
+
+   p.to_xarray()
+
+You can see the full-documentation for the `xarray package <http://xarray.pydata.org/en/stable/>`__.
+
 .. _dsintro.panelnd:
 .. _dsintro.panel4d:
 

doc/source/whatsnew/v0.20.0.txt

@@ -433,7 +433,7 @@ Deprecate Panel
 
 ``Panel`` is deprecated and will be removed in a future version. The recommended way to represent 3-D data are
 with a ``MultiIndex``on a ``DataFrame`` via the :meth:`~Panel.to_frame` or with the `xarray package <http://xarray.pydata.org/en/stable/>`__. Pandas
-provides a :meth:`~Panel.to_xarray` method to automate this conversion (:issue:`13563`).
+provides a :meth:`~Panel.to_xarray` method to automate this conversion. See the documentation :ref:`Deprecate Panel <dsintro.deprecate_panel>`. (:issue:`13563`).
 
 .. ipython:: python
    :okwarning:
@@ -445,7 +445,7 @@ Convert to a MultiIndex DataFrame
 
 .. ipython:: python
 
-   p.frame()
+   p.to_frame()
 
 Convert to an xarray DataArray
 

pandas/core/panel.py

@@ -136,8 +136,8 @@ def __init__(self, data=None, items=None, major_axis=None, minor_axis=None,
                       "these types of 3-dimensional data are with a "
                       "MultiIndex on a DataFrame, via the "
                       "Panel.to_frame() method\n"
-                      "alternatively, you can use the `xarray package "
-                      "<http://xarray.pydata.org/en/stable/>`__.\n"
+                      "Alternatively, you can use the xarray package "
+                      "http://xarray.pydata.org/en/stable/.\n"
                       "Pandas provides a `.to_xarray()` method to help "
                       "automate this conversion.\n",
                       DeprecationWarning, stacklevel=3)