DOC: update Series.sort_values docstring
State: closed

Co-authored-by: @marielen

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.core.series.Series.sort_values)  ##############
################################################################################

Sort by the values.

Sort a Series in ascending or descending order by some
criterion.

Parameters
----------
axis : {0 or 'index'}, default 0
    Axis to direct sorting. The value 'index' is accepted for
    compatibility with DataFrame.sort_values.
ascending : bool, default True
    If  True sort values in ascending order, otherwise descending.
inplace : bool, default False
    If True, perform operation in-place.
kind : {'quicksort', 'mergesort' or 'heapsort'}, default 'quicksort'
    Choice of sorting algorithm. See also :func:'numpy.sort' for more
    information. 'mergesort' is the only stable  algorithm.
na_position : {'first' or 'last'}, default 'last'
    Argument 'first' puts NaNs at the beginning, 'last' puts NaNs at
    the end.

Returns
-------
Series
    Series ordered by values.

See Also
--------
Series.sort_index : Sort by the Series indices.
DataFrame.sort_index : Sort DataFrame by indices.
DataFrame.sort_values : Sort by the values along either axis.

Examples
--------
>>> s = pd.Series([np.nan, 1, 3, 10, 5])
>>> s
0     NaN
1     1.0
2     3.0
3     10.0
4     5.0
dtype: float64

Sort values ascending order (default behaviour)

>>> s.sort_values(ascending=True)
1     1.0
2     3.0
4     5.0
3    10.0
0     NaN
dtype: float64

Sort values descending order

>>> s.sort_values(ascending=False)
3    10.0
4     5.0
2     3.0
1     1.0
0     NaN
dtype: float64

Sort values inplace

>>> s.sort_values(ascending=False, inplace=True)
>>> s
3    10.0
4     5.0
2     3.0
1     1.0
0     NaN
dtype: float64

Sort values putting NAs first

>>> s.sort_values(na_position='first')
0     NaN
1     1.0
2     3.0
4     5.0
3    10.0
dtype: float64

Sort a series of strings

>>> s = pd.Series(['z', 'b', 'd', 'a', 'c'])
>>> s
0    z
1    b
2    d
3    a
4    c
dtype: object

>>> s.sort_values()
3    a
1    b
4    c
2    d
0    z
dtype: object

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.core.series.Series.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: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode

Comments:
Hello @rafarui! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 12, 2018 at 14:59 Hours UTC
Can you follow the guidelines please: paste the output of the validation script above (you can still edit your top post). And check PEP8 as well, as you have some errors there.
lgtm. @jorisvandenbossche 
@rafarui Thanks a lot!