DOC: add documentation to IndexSlice

doc/source/api.rst

@@ -1405,6 +1405,7 @@ MultiIndex
    :toctree: generated/
 
    MultiIndex
+   IndexSlice
 
 MultiIndex Components
 ~~~~~~~~~~~~~~~~~~~~~~

pandas/core/indexing.py

@@ -43,7 +43,37 @@ def get_indexers_list():
 
 # the public IndexSlicerMaker
 class _IndexSlice(object):
-
+    """
+    Create an object to more easily perform multi-index slicing
+
+    Examples
+    --------
+
+    >>> miindex = pd.MultiIndex.from_product([['A0','A1'],['B0','B1','B2','B3']])
+    >>> columns = ['foo','bar']
+    >>> dfmi = pd.DataFrame(np.arange(16).reshape((len(miindex),len(columns))),
+                          index=miindex,columns=columns)
+
+    Using the default slice command:
+
+    >>> dfmi.loc[(slice(None),slice('B0','B1')),:] 
+               foo  bar
+        A0 B0    0    1
+           B1    2    3
+        A1 B0    8    9
+           B1   10   11
+
+    Using the IndexSlice class for a more intuitive command:
+
+    >>> idx = pd.IndexSlice
+    >>> dfmi.loc[idx[:,['B0','B1']],:]
+               foo  bar
+        A0 B0    0    1
+           B1    2    3
+        A1 B0    8    9
+           B1   10   11
+    """
+
     def __getitem__(self, arg):
         return arg