DOC: update the Index.sort_values docstring

[DataOmbudsman]

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

• PR title is "DOC: update the docstring"
• The validation script passes: scripts/validate_docstrings.py <your-function-or-method>
• The PEP8 style check passes: git diff upstream/master -u -- "*.py" | flake8 --diff
• The html version looks good: python doc/make.py --single <your-function-or-method>
• It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

################################################################################
##################### Docstring (pandas.Index.sort_values) #####################
################################################################################

Return a sorted copy of the index.

Return a sorted copy of the index, and optionally return the indices
that sorted the index itself.

Parameters
----------
return_indexer : bool, default False
    Should the indices that would sort the index be returned.
ascending : bool, default True
    Should the index values be sorted in an ascending order.

Returns
-------
sorted_index : pandas.Index
    Sorted copy of the index.
_as : numpy.ndarray, optional
    The indices that the index itself was sorted by.

See Also
--------
pandas.Series.sort_values : Sort values of a Series.
pandas.DataFrame.sort_values : Sort values in a DataFrame.

Examples
--------
>>> idx = pd.Index([10, 100, 1, 1000])
>>> idx
Int64Index([10, 100, 1, 1000], dtype='int64')

Sort values in ascending order (default behavior).

>>> idx.sort_values()
Int64Index([1, 10, 100, 1000], dtype='int64')

Sort values in descending order, and also get the indices `idx` was
sorted by.

>>> idx.sort_values(ascending=False, return_indexer=True)
(Int64Index([1000, 100, 10, 1], dtype='int64'), array([3, 1, 0, 2]))

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.Index.sort_values" correct. :)

If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

[TomAugspurger]

Small change, LGTM otherwise.

[TomAugspurger]

I think numpy usually calls this kind of array an indexer or index_array.

[DataOmbudsman]

Sure, that's better

[codecov]

Codecov Report

Merging #20299 into master will not change coverage.
The diff coverage is n/a.

@@           Coverage Diff           @@
##           master   #20299   +/-   ##
=======================================
  Coverage   91.73%   91.73%           
=======================================
  Files         150      150           
  Lines       49168    49168           
=======================================
  Hits        45102    45102           
  Misses       4066     4066

Flag	Coverage Δ
#multiple	90.11% <ø> (ø)	⬆️
#single	41.86% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/core/indexes/base.py	96.66% <ø> (ø)	⬆️

---

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 0815c43...2d0f820. Read the comment docs.

[TomAugspurger]

💯 Thanks @DataOmbudsman!