Fix DataFrame/Series stack/unstack docs

Author: Minh Phan

doc/source/whatsnew/v1.1.0.rst

@@ -966,6 +966,7 @@ MultiIndex
         left.intersection(right, sort=False)
 
 - Bug when joining 2 Multi-indexes, without specifying level with different columns. Return-indexers parameter is ignored. (:issue:`34074`)
+- Bug in :meth:`DataFrame.stack`, :meth:`DataFrame.unstack`, :meth:`Series.unstack` where the level involved is not always sorted (:issue:`21675`)
 
 I/O
 ^^^

pandas/core/frame.py

@@ -6739,8 +6739,6 @@ def stack(self, level=-1, dropna=True):
             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, str, list, default -1
@@ -6976,8 +6974,6 @@ def unstack(self, level=-1, fill_value=None):
         If the index is not a MultiIndex, the output will be a Series
         (the analogue of stack when the columns are not a MultiIndex).
 
-        The level involved will automatically get sorted.
-
         Parameters
         ----------
         level : int, str, or list of these, default -1 (last level)

pandas/core/series.py

@@ -3823,8 +3823,6 @@ def unstack(self, level=-1, fill_value=None):
         """
         Unstack, also known as pivot, Series with MultiIndex to produce DataFrame.
 
-        The level involved will automatically get sorted.
-
         Parameters
         ----------
         level : int, str, or list of these, default last level