From 5a183d8714c4720bb4e33e08491cd11e1d720564 Mon Sep 17 00:00:00 2001
From: Attila Nemet <Attila.Nemet@gmail.com>
Date: Sat, 10 Mar 2018 21:20:56 +0100
Subject: [PATCH 1/4] DOC: update the pd.Index.argsort docstring

---
 pandas/core/indexes/base.py | 28 ++++++++++++++++++++++++----
 1 file changed, 24 insertions(+), 4 deletions(-)

diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index fd1d3690e8a89..7b1acc77be022 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -2316,16 +2316,36 @@ def shift(self, periods=1, freq=None):
 
     def argsort(self, *args, **kwargs):
         """
-        Returns the indices that would sort the index and its
-        underlying data.
+        Return the order of the indices that would sort the index.
+
+        Parameters
+        ----------
+        *args
+            Passed to `numpy.ndarray.argsort`.
+        **kwargs
+            Passed to `numpy.ndarray.argsort`.
 
         Returns
         -------
-        argsorted : numpy array
+        numpy.ndarray
+            Argsorted indices of the index
 
         See also
         --------
-        numpy.ndarray.argsort
+        numpy.ndarray.argsort : Similar method for NumPy arrays.
+        pd.Index.sort_values : Return sorted copy of Index
+
+        Examples
+        --------
+        >>> pd.Index(['b','a','d','c']).argsort()
+        array([1, 0, 3, 2], dtype=int64)
+
+        When applying argsort to a Series object then the result won't
+        be affected by Series values only by Series index.
+
+        >>> s = pd.Series(data=[4, 3, 2, 1], index=['c', 'b', 'a', 'd'])
+        >>> s.index.argsort()
+        array([2, 1, 0, 3], dtype=int64)
         """
         result = self.asi8
         if result is None:

From d42113115c77039f23454209030691b80d31b10b Mon Sep 17 00:00:00 2001
From: Tom Augspurger <tom.w.augspurger@gmail.com>
Date: Mon, 12 Mar 2018 12:15:02 -0500
Subject: [PATCH 2/4] Updated

---
 pandas/core/indexes/base.py | 22 ++++++++++++----------
 1 file changed, 12 insertions(+), 10 deletions(-)

diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index 7b1acc77be022..e15df0f7f34ca 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -2328,24 +2328,26 @@ def argsort(self, *args, **kwargs):
         Returns
         -------
         numpy.ndarray
-            Argsorted indices of the index
+            indicies that would sort the index if used as
+            an indexer.
 
         See also
         --------
-        numpy.ndarray.argsort : Similar method for NumPy arrays.
-        pd.Index.sort_values : Return sorted copy of Index
+        numpy.argsort : Similar method for NumPy arrays.
+        Index.sort_values : Return sorted copy of Index
 
         Examples
         --------
-        >>> pd.Index(['b','a','d','c']).argsort()
-        array([1, 0, 3, 2], dtype=int64)
+        >>> idx = pd.Index(['b', 'a', 'd', 'c'])
+        >>> idx
+        Index(['b', 'a', 'd', 'c'], dtype='object')
 
-        When applying argsort to a Series object then the result won't
-        be affected by Series values only by Series index.
+        >>> order = idx.argsort()
+        >>> order
+        array([1, 0, 3, 2])
 
-        >>> s = pd.Series(data=[4, 3, 2, 1], index=['c', 'b', 'a', 'd'])
-        >>> s.index.argsort()
-        array([2, 1, 0, 3], dtype=int64)
+        >>> idx[order]
+        Index(['a', 'b', 'c', 'd'], dtype='object')
         """
         result = self.asi8
         if result is None:

From 2ea541694e7dd940dbe6987c4ce4d5323c086795 Mon Sep 17 00:00:00 2001
From: Tom Augspurger <tom.w.augspurger@gmail.com>
Date: Mon, 12 Mar 2018 12:16:16 -0500
Subject: [PATCH 3/4] Clarify

---
 pandas/core/indexes/base.py | 4 ++--
 1 file changed, 2 insertions(+), 2 deletions(-)

diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index e15df0f7f34ca..5c8e94c2340ae 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -2316,7 +2316,7 @@ def shift(self, periods=1, freq=None):
 
     def argsort(self, *args, **kwargs):
         """
-        Return the order of the indices that would sort the index.
+        Return the integer indicies that would sort the index.
 
         Parameters
         ----------
@@ -2328,7 +2328,7 @@ def argsort(self, *args, **kwargs):
         Returns
         -------
         numpy.ndarray
-            indicies that would sort the index if used as
+            Integer indicies that would sort the index if used as
             an indexer.
 
         See also

From 4a61dd49b77be2c814c0ea22d7ca11414783be5d Mon Sep 17 00:00:00 2001
From: Tom Augspurger <tom.w.augspurger@gmail.com>
Date: Mon, 12 Mar 2018 12:16:58 -0500
Subject: [PATCH 4/4] Missing .

---
 pandas/core/indexes/base.py | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/pandas/core/indexes/base.py b/pandas/core/indexes/base.py
index 5c8e94c2340ae..5edb031c7442c 100644
--- a/pandas/core/indexes/base.py
+++ b/pandas/core/indexes/base.py
@@ -2334,7 +2334,7 @@ def argsort(self, *args, **kwargs):
         See also
         --------
         numpy.argsort : Similar method for NumPy arrays.
-        Index.sort_values : Return sorted copy of Index
+        Index.sort_values : Return sorted copy of Index.
 
         Examples
         --------