DOC: update the Index.sort_values docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [x] PR title is "DOC: update the <your-function-or-method> docstring"
- [x] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [x] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [x] 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.



Labels:
name: Docs
name: Algos
description: Non-arithmetic algos: value_counts, factorize, sorting, isin, clip, shift, diff

Comments:
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=h1) Report
> Merging [#20299](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0815c433b58920c658f1be9c7eb00cf7e75a3e2b?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

[![Impacted file tree graph](https://codecov.io/gh/pandas-dev/pandas/pull/20299/graphs/tree.svg?width=650&height=150&src=pr&token=eZ4WkYLtcO)](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=tree)

```diff
@@           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% <ø> (ø)` | :arrow_up: |
| #single | `41.86% <ø> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/indexes/base.py](https://codecov.io/gh/pandas-dev/pandas/pull/20299/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9iYXNlLnB5) | `96.66% <ø> (ø)` | :arrow_up: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=continue).
> **Legend** - [Click here to learn more](https://docs.codecov.io/docs/codecov-delta)
> `Δ = absolute <relative> (impact)`, `ø = not affected`, `? = missing data`
> Powered by [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=footer). Last update [0815c43...2d0f820](https://codecov.io/gh/pandas-dev/pandas/pull/20299?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

💯 Thanks @DataOmbudsman!