updating docs for the new sorting mechanisms - GH #10886

Author: glyg

doc/source/10min.rst

@@ -157,7 +157,7 @@ Sorting by values
 
 .. ipython:: python
 
-   df.sort(columns='B')
+   df.sort_values(by='B')
 
 Selection
 ---------
@@ -680,7 +680,7 @@ Sorting is per order in the categories, not lexical order.
 
 .. ipython:: python
 
-    df.sort("grade")
+    df.sort_values(by="grade")
 
 Grouping by a categorical column shows also empty categories.
 

doc/source/advanced.rst

@@ -286,7 +286,7 @@ As usual, **both sides** of the slicers are included as this is label indexing.
                                          names=['lvl0', 'lvl1'])
    dfmi = pd.DataFrame(np.arange(len(miindex)*len(micolumns)).reshape((len(miindex),len(micolumns))),
                        index=miindex,
-                       columns=micolumns).sortlevel().sortlevel(axis=1)
+                       columns=micolumns).sort_index().sort_index(axis=1)
    dfmi
 
 Basic multi-index slicing using slices, lists, and labels.
@@ -458,7 +458,7 @@ correctly. You can think about breaking the axis into unique groups, where at
 the hierarchical level of interest, each distinct group shares a label, but no
 two have the same label. However, the ``MultiIndex`` does not enforce this:
 **you are responsible for ensuring that things are properly sorted**. There is
-an important new method ``sortlevel`` to sort an axis within a ``MultiIndex``
+an important new method ``sort_index`` to sort an axis within a ``MultiIndex``
 so that its labels are grouped and sorted by the original ordering of the
 associated factor at that level. Note that this does not necessarily mean the
 labels will be sorted lexicographically!
@@ -468,34 +468,34 @@ labels will be sorted lexicographically!
    import random; random.shuffle(tuples)
    s = pd.Series(np.random.randn(8), index=pd.MultiIndex.from_tuples(tuples))
    s
-   s.sortlevel(0)
-   s.sortlevel(1)
+   s.sort_index(level=0)
+   s.sort_index(level=1)
 
 .. _advanced.sortlevel_byname:
 
-Note, you may also pass a level name to ``sortlevel`` if the MultiIndex levels
+Note, you may also pass a level name to ``sort_index`` if the MultiIndex levels
 are named.
 
 .. ipython:: python
 
    s.index.set_names(['L1', 'L2'], inplace=True)
-   s.sortlevel(level='L1')
-   s.sortlevel(level='L2')
+   s.sort_index(level='L1')
+   s.sort_index(level='L2')
 
 Some indexing will work even if the data are not sorted, but will be rather
 inefficient and will also return a copy of the data rather than a view:
 
 .. ipython:: python
 
    s['qux']
-   s.sortlevel(1)['qux']
+   s.sort_index(level=1)['qux']
 
 On higher dimensional objects, you can sort any of the other axes by level if
 they have a MultiIndex:
 
 .. ipython:: python
 
-   df.T.sortlevel(1, axis=1)
+   df.T.sort_index(level=1, axis=1)
 
 The ``MultiIndex`` object has code to **explicity check the sort depth**. Thus,
 if you try to index at a depth at which the index is not sorted, it will raise

doc/source/api.rst

@@ -437,7 +437,6 @@ Reshaping, sorting
    Series.reorder_levels
    Series.sort_values
    Series.sort_index
-   Series.sortlevel
    Series.swaplevel
    Series.unstack
    Series.searchsorted

doc/source/basics.rst

@@ -328,7 +328,7 @@ equality to be True:
    df1 = pd.DataFrame({'col':['foo', 0, np.nan]})
    df2 = pd.DataFrame({'col':[np.nan, 0, 'foo']}, index=[2,1,0])
    df1.equals(df2)
-   df1.equals(df2.sort())
+   df1.equals(df2.sort_index())
 
 Comparing array-like objects
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
@@ -1489,16 +1489,16 @@ The ``by`` argument can take a list of column names, e.g.:
 
 .. ipython:: python
 
-   df1[['one', 'two', 'three']].sort_index(by=['one','two'])
+   df1[['one', 'two', 'three']].sort_values(by=['one','two'])
 
 These methods have special treatment of NA values via the ``na_position``
 argument:
 
 .. ipython:: python
 
    s[2] = np.nan
-   s.order()
-   s.order(na_position='first')
+   s.sort_values()
+   s.sort_values(na_position='first')
 
 
 .. _basics.searchsorted:
@@ -1564,7 +1564,7 @@ all levels to ``by``.
 .. ipython:: python
 
    df1.columns = pd.MultiIndex.from_tuples([('a','one'),('a','two'),('b','three')])
-   df1.sort_index(by=('a','two'))
+   df1.sort_values(by=('a','two'))
 
 
 Copying

doc/source/cookbook.rst

@@ -309,7 +309,7 @@ Method 2 : sort then take first of each
 
 .. ipython:: python
 
-   df.sort("BBB").groupby("AAA", as_index=False).first()
+   df.sort_values(by="BBB").groupby("AAA", as_index=False).first()
 
 Notice the same results, with the exception of the index.
 
@@ -410,7 +410,7 @@ Sorting
 
 .. ipython:: python
 
-   df.sort(('Labs', 'II'), ascending=False)
+   df.sort_values(by=('Labs', 'II'), ascending=False)
 
 `Partial Selection, the need for sortedness;
 <https://github.com/pydata/pandas/issues/2995>`__
@@ -547,7 +547,7 @@ Unlike agg, apply's callable is passed a sub-DataFrame which gives you access to
 
    code_groups = df.groupby('code')
 
-   agg_n_sort_order = code_groups[['data']].transform(sum).sort('data')
+   agg_n_sort_order = code_groups[['data']].transform(sum).sort_values(by='data')
 
    sorted_df = df.ix[agg_n_sort_order.index]
 

doc/source/reshaping.rst

@@ -164,9 +164,9 @@ will result in a **sorted** copy of the original DataFrame or Series:
    index = pd.MultiIndex.from_product([[2,1], ['a', 'b']])
    df = pd.DataFrame(np.random.randn(4), index=index, columns=['A'])
    df
-   all(df.unstack().stack() == df.sort())
+   all(df.unstack().stack() == df.sort_index())
 
-while the above code will raise a ``TypeError`` if the call to ``sort`` is
+while the above code will raise a ``TypeError`` if the call to ``sort_index`` is
 removed.
 
 .. _reshaping.stack_multiple:
@@ -206,7 +206,7 @@ Missing Data
 These functions are intelligent about handling missing data and do not expect
 each subgroup within the hierarchical index to have the same set of labels.
 They also can handle the index being unsorted (but you can make it sorted by
-calling ``sortlevel``, of course). Here is a more complex example:
+calling ``sort_index``, of course). Here is a more complex example:
 
 .. ipython:: python