DOC: Add examples to Series.str.slice() with negative arguments GH27802
State: closed

- [x] closes #27802 
- [x] tests added / passed
- [x] passes `black pandas`
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [N/A] whatsnew entry


Labels:
name: Docs

Comments:
Hello @phillipwalters! Thanks for updating this PR. We checked the lines you've touched for [PEP 8](https://www.python.org/dev/peps/pep-0008) issues, and found:



There are currently no PEP 8 issues detected in this Pull Request. Cheers! :beers: 

##### Comment last updated at 2019-08-09 04:50:22 UTC
$ python scripts/validate_docstrings.py pandas.Series.str.slice

################################################################################
##################### Docstring (pandas.Series.str.slice)  #####################
################################################################################

Slice substrings from each element in the Series or Index.

Parameters
----------
start : int, optional
    Start position for slice operation.
stop : int, optional
    Stop position for slice operation.
step : int, optional
    Step size for slice operation.

Returns
-------
Series or Index of object
    Series or Index from sliced substring from original string object.

See Also
--------
Series.str.slice_replace : Replace a slice with a string.
Series.str.get : Return element at position.
    Equivalent to `Series.str.slice(start=i, stop=i+1)` with `i`
    being the position.

Examples
--------
>>> s = pd.Series(["koala", "fox", "chameleon"])
>>> s
0        koala
1          fox
2    chameleon
dtype: object

>>> s.str.slice(start=1)
0        oala
1          ox
2    hameleon
dtype: object

>>> s.str.slice(stop=2)
0    ko
1    fo
2    ch
dtype: object

>>> s.str.slice(step=2)
0      kaa
1       fx
2    caeen
dtype: object

Negative values can be used for any of the three parameters. For start or stop, a value of -1 will be the last
character of the string, -2 the second to last, and so on. Examples:

>>> s.str.slice(start=-3)
0    ala
1    fox
2    eon
dtype: object

>>> s.str.slice(stop=-2)
0        koa
1          f
2    chamele
dtype: object

A negative value for step will simply step in the other direction.

>>> s.str.slice(step=-1)
0        alaok
1          xof
2    noelemahc
dtype: object

>>> s.str.slice(stop=1, step=-1)
0        ala
1          x
2    noelema
dtype: object

>>> s.str.slice(start=0, stop=5, step=3)
0    kl
1     f
2    cm
dtype: object

Equivalent behaviour to:

>>> s.str[0:5:3]
0    kl
1     f
2    cm
dtype: object

################################################################################
################################## Validation ##################################
################################################################################

1 Warnings found:
        No extended summary found
Docstring for "pandas.Series.str.slice" correct. :)
This is a bit too much, and a single example with negative indexes is enough. If you wantvto to rebase and add the text snippet, that would be nice.
Seems like https://github.com/pandas-dev/pandas/pull/27832/files also worked on this. @phillipwalters perhaps just add one more example showing a negative slice to reverse the string?
@phillipwalters Maybe add an example that uses the shorthand notation, e.g.:
```
In [6]: s.str[:-1]
Out[6]:
0      A
1     BC
2    DEF
dtype: object
```
I saw his PR shortly after I submitted this one, and it looks like you guys went with that one. Sounds like the right choice to me. Thanks for your guys' suggestions, though!