small doc updates

Author: jreback

doc/source/advanced.rst

@@ -136,7 +136,7 @@ can find yourself working with hierarchically-indexed data without creating a
 may wish to generate your own ``MultiIndex`` when preparing the data set.
 
 Note that how the index is displayed by be controlled using the
-``multi_sparse`` option in ``pandas.set_printoptions``:
+``multi_sparse`` option in ``pandas.set_options()``:
 
 .. ipython:: python
 
@@ -288,7 +288,7 @@ As usual, **both sides** of the slicers are included as this is label indexing.
 
    .. code-block:: python
 
-      df.loc[(slice('A1','A3'),.....),:]
+      df.loc[(slice('A1','A3'),.....), :]
 
    rather than this:
 
@@ -317,51 +317,51 @@ Basic multi-index slicing using slices, lists, and labels.
 
 .. ipython:: python
 
-   dfmi.loc[(slice('A1','A3'),slice(None), ['C1','C3']),:]
+   dfmi.loc[(slice('A1','A3'), slice(None), ['C1', 'C3']), :]
 
 You can use a ``pd.IndexSlice`` to have a more natural syntax using ``:`` rather than using ``slice(None)``
 
 .. ipython:: python
 
    idx = pd.IndexSlice
-   dfmi.loc[idx[:,:,['C1','C3']],idx[:,'foo']]
+   dfmi.loc[idx[:, :, ['C1', 'C3']], idx[:, 'foo']]
 
 It is possible to perform quite complicated selections using this method on multiple
 axes at the same time.
 
 .. ipython:: python
 
-   dfmi.loc['A1',(slice(None),'foo')]
-   dfmi.loc[idx[:,:,['C1','C3']],idx[:,'foo']]
+   dfmi.loc['A1', (slice(None), 'foo')]
+   dfmi.loc[idx[:, :, ['C1', 'C3']], idx[:, 'foo']]
 
 Using a boolean indexer you can provide selection related to the *values*.
 
 .. ipython:: python
 
-   mask = dfmi[('a','foo')]>200
-   dfmi.loc[idx[mask,:,['C1','C3']],idx[:,'foo']]
+   mask = dfmi[('a', 'foo')] > 200
+   dfmi.loc[idx[mask, :, ['C1', 'C3']], idx[:, 'foo']]
 
 You can also specify the ``axis`` argument to ``.loc`` to interpret the passed
 slicers on a single axis.
 
 .. ipython:: python
 
-   dfmi.loc(axis=0)[:,:,['C1','C3']]
+   dfmi.loc(axis=0)[:, :, ['C1', 'C3']]
 
 Furthermore you can *set* the values using these methods
 
 .. ipython:: python
 
    df2 = dfmi.copy()
-   df2.loc(axis=0)[:,:,['C1','C3']] = -10
+   df2.loc(axis=0)[:, :, ['C1', 'C3']] = -10
    df2
 
 You can use a right-hand-side of an alignable object as well.
 
 .. ipython:: python
 
    df2 = dfmi.copy()
-   df2.loc[idx[:,:,['C1','C3']],:] = df2*1000
+   df2.loc[idx[:, :, ['C1', 'C3']], :] = df2 * 1000
    df2
 
 .. _advanced.xs:

doc/source/whatsnew/v0.20.0.txt

@@ -662,7 +662,7 @@ DataFrame.sort_index changes
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 In certain cases, calling ``.sort_index()`` on a MultiIndexed DataFrame would return the *same* DataFrame without seeming to sort.
-This would happen with a ``lexsorted``, but non-montonic levels. (:issue:`15622`, :issue:`15687`, :issue:`14015`, :issue:`13431`)
+This would happen with a ``lexsorted``, but non-monotonic levels. (:issue:`15622`, :issue:`15687`, :issue:`14015`, :issue:`13431`)
 
 This is UNCHANGED between versions, but showing for illustration purposes:
 
@@ -720,15 +720,6 @@ New Behavior:
    df.sort_index().index.is_lexsorted()
    df.sort_index().index.is_monotonic
 
-Previous Behavior:
-
-.. code-block:: ipython
-
-New Behavior:
-
-.. ipython:: python
-
-
 .. _whatsnew_0200.api_breaking.groupby_describe:
 
 Groupby Describe Formatting

pandas/core/sorting.py

@@ -94,6 +94,22 @@ def maybe_lift(lab, size):  # pormote nan values
 
 
 def get_compressed_ids(labels, sizes):
+    """
+
+    Group_index is offsets into cartesian product of all possible labels. This
+    space can be huge, so this function compresses it, by computing offsets
+    (comp_ids) into the list of unique labels (obs_group_ids).
+
+    Parameters
+    ----------
+    labels : list of label arrays
+    sizes : list of size of the levels
+
+    Returns
+    -------
+    tuple of (comp_ids, obs_group_ids)
+
+    """
     ids = get_group_index(labels, sizes, sort=True, xnull=False)
     return compress_group_index(ids, sort=True)
 

pandas/indexes/multi.py

@@ -1177,10 +1177,14 @@ def from_product(cls, iterables, sortorder=None, names=None):
 
     def _reconstruct(self, sort=False, remove_unused=False):
         """
-        reconstruct the MultiIndex
+        create a new MultiIndex from the current to provide either:
+          - monotonically sorted items IN the levels
+          - removing unused levels (meaning that they are not expressed
+            in the labels)
 
-        The MultiIndex will have the same outward appearance (e.g. values)
-        and will also .equals()
+        The resulting MultiIndex will have the same outward
+        appearance, meaning the same .values and ordering. It will also
+        be .equals() to the original.
 
         Parameters
         ----------
@@ -1191,7 +1195,7 @@ def _reconstruct(self, sort=False, remove_unused=False):
 
         Returns
         -------
-        MultiIndex
+        new MultiIndex
 
         """