DOC: Improve docstring for pandas.Index.repeat (pandas-dev#19985)

Author: alysivji

pandas/core/indexes/base.py

@@ -696,12 +696,38 @@ def memory_usage(self, deep=False):
  @deprecate_kwarg(old_arg_name='n', new_arg_name='repeats')
  def repeat(self, repeats, *args, **kwargs):
  """
- Repeat elements of an Index. Refer to `numpy.ndarray.repeat`
- for more information about the `repeats` argument.
+ Repeat elements of an Index.
 
- See also
+ Returns a new index where each element of the current index
+ is repeated consecutively a given number of times.
+
+ Parameters
+ ----------
+ repeats : int
+ The number of repetitions for each element.
+ **kwargs
+ Additional keywords have no effect but might be accepted for
+ compatibility with numpy.
+
+ Returns
+ -------
+ pandas.Index
+ Newly created Index with repeated elements.
+
+ See Also
+ --------
+ Series.repeat : Equivalent function for Series
+ numpy.repeat : Underlying implementation
+
+ Examples
  --------
- numpy.ndarray.repeat
+ >>> idx = pd.Index([1, 2, 3])
+ >>> idx
+ Int64Index([1, 2, 3], dtype='int64')
+ >>> idx.repeat(2)
+ Int64Index([1, 1, 2, 2, 3, 3], dtype='int64')
+ >>> idx.repeat(3)
+ Int64Index([1, 1, 1, 2, 2, 2, 3, 3, 3], dtype='int64')
  """
  nv.validate_repeat(args, kwargs)
  return self._shallow_copy(self._values.repeat(repeats))