DOC: update the DataFrame.stack docstring

pandas/core/frame.py

@@ -5145,36 +5145,151 @@ def pivot_table(self, values=None, index=None, columns=None,
 
     def stack(self, level=-1, dropna=True):
         """
-        Pivot a level of the (possibly hierarchical) column labels, returning a
-        DataFrame (or Series in the case of an object with a single level of
-        column labels) having a hierarchical index with a new inner-most level
-        of row labels.
-        The level involved will automatically get sorted.
+        Stack the prescribed level(s) from the column axis onto the index
+        axis.
+
+        Return a reshaped DataFrame or Series having a multi-level
+        index with one or more new inner-most levels compared to the current
+        dataframe. The new inner-most levels are created by pivoting the
+        columns of the current dataframe:
+
+          - if the columns have a single level, the output is a Series;
+          - if the columns have multiple levels, the new index
+            level(s) is (are) taken from the prescribed level(s) and
+            the output is a DataFrame.
+
+        The new index levels are sorted.
 
         Parameters
         ----------
-        level : int, string, or list of these, default last level
-            Level(s) to stack, can pass level name
-        dropna : boolean, default True
-            Whether to drop rows in the resulting Frame/Series with no valid
-            values
+        level : int, str, list, default -1
+            Level(s) to stack from the column axis onto the index
+            axis, defined as one index or label, or a list of indices
+            or labels.
+        dropna : bool, default True
+            Whether to drop rows in the resulting Frame/Series with
+            missing values. Stacking a column level onto the index
+            axis can create combinations of index and column values
+            that are missing from the original dataframe. See Examples
+            section.
+
+        Notes
+        -----
+        The function is named by analogy with a stack of books
+        (levels) being re-organised from a horizontal position (column
+        levels) to a vertical position (index levels).
 
         Examples
-        ----------
-        >>> s
+        --------
+        >>> df_single_level_cols = pd.DataFrame([[0, 1], [2, 3]],
+        ...                                     index=['one', 'two'],
+        ...                                     columns=['a', 'b'])
+        >>> multicol1 = pd.MultiIndex.from_tuples([('X', 'a'), ('X', 'b')])
+        >>> df_multi_level_cols1 = pd.DataFrame([[0, 1], [2, 3]],
+        ...                                    index=['one', 'two'],
+        ...                                    columns=multicol1)
+        >>> multicol2 = pd.MultiIndex.from_tuples([('X', 'a'), ('Y', 'b')])
+        >>> df_multi_level_cols2 = pd.DataFrame([[0.0, 1.0], [2.0, 3.0]],
+        ...                                     index=['one', 'two'],
+        ...                                     columns=multicol2)
+        >>> df_multi_level_cols3 = pd.DataFrame([[None, 1.0], [2.0, 3.0]],
+        ...                                     index=['one', 'two'],
+        ...                                     columns=multicol2)
+
+        Stacking a dataframe with a single level column axis returns a Series:
+
+        >>> df_single_level_cols
              a   b
-        one  1.  2.
-        two  3.  4.
+        one  0   1
+        two  2   3
+        >>> df_single_level_cols.stack()
+        one  a    0
+             b    1
+        two  a    2
+             b    3
+        dtype: int64
+
+        Stacking a dataframe with a multi-level column axis:
+
+        >>> df_multi_level_cols1
+             X
+             a   b
+        one  0   1
+        two  2   3
+        >>> df_multi_level_cols1.stack()
+                  X
+        one  a    0
+             b    1
+        two  a    2
+             b    3
+
+        It is common to have missing values when stacking a dataframe
+        with multi-level columns, as the stacked dataframe typically
+        has more values than the original dataframe. Missing values
+        are filled with NaNs:
+
+        >>> df_multi_level_cols2
+               X     Y
+               a     b
+        one  0.0   1.0
+        two  2.0   3.0
+        >>> df_multi_level_cols2.stack()
+                 X    Y
+        one a  0.0  NaN
+            b  NaN  1.0
+        two a  2.0  NaN
+            b  NaN  3.0
+
+        The first parameter controls which level or levels are stacked:
+
+        >>> df_multi_level_cols2.stack(0)
+                 a    b
+        one X  0.0  NaN
+            Y  NaN  1.0
+        two X  2.0  NaN
+            Y  NaN  3.0
+        >>> df_multi_level_cols2.stack([0, 1])
+        one  X  a    0.0
+             Y  b    1.0
+        two  X  a    2.0
+             Y  b    3.0
+        dtype: float64
 
-        >>> s.stack()
-        one a    1
-            b    2
-        two a    3
-            b    4
+        Note that rows where all values are missing are dropped by
+        default but this behaviour can be controlled via the dropna
+        keyword parameter:
+
+        >>> df_multi_level_cols3
+               X     Y
+               a     b
+        one  NaN   1.0
+        two  2.0   3.0
+        >>> df_multi_level_cols3.stack(dropna=False)
+                 X    Y
+        one a  NaN  NaN
+            b  NaN  1.0
+        two a  2.0  NaN
+            b  NaN  3.0
+
+        >>> df_multi_level_cols3.stack(dropna=True)
+                 X    Y
+        one b  NaN  1.0
+        two a  2.0  NaN
+            b  NaN  3.0
 
         Returns
         -------
-        stacked : DataFrame or Series
+        DataFrame or Series
+            Stacked dataframe or series.
+
+        See Also
+        --------
+        DataFrame.unstack: unstack prescribed level(s) from index axis
+             onto column axis.
+        DataFrame.pivot: reshape dataframe from long format to wide
+             format.
+        DataFrame.pivot_table: create a spreadsheet-style pivot table
+             as a DataFrame.
         """
         from pandas.core.reshape.reshape import stack, stack_multiple