DOC: improve the shared docstring of Series.str.strip()

[alsobay]

• closes #xxxx
• tests added / passed
• passes git diff upstream/master -u -- "*.py" | flake8 --diff
• whatsnew entry

Docstring written with @jalammar as part of the pandas sprint at PyData London 2018, guided by @datapythonista. Wasn't too sure of the "Return" definition, so we defaulted to the one written for str_strip. Docstring is shared by the strip, lstrip, and rstrip methods, and validate_docstrings.py script output for the "script" variant is included below:

################################################################################
##################### Docstring (pandas.Series.str.strip) #####################
################################################################################

Strip combinations of characters from the left and right sides of strings.

Operates on each element in the given String/Index, and is equivalent to
:meth:str.strip.

Parameters

to_strip : str or unicode, optional
String or unicode specifying the set of characters to be removed from
the left and right sides. If omitted or None, the strip method defaults to removing
whitespace and newlines.

Returns

stripped : Series/Index of objects

See Also

Series.str.strip : Removes defined characters from both sides
Series.str.lstrip : Removes defined characters from the left side
Series.str.rstrip : Removes defined characters from the right side

Examples

s = pd.Series(data=[' spacious ', '-left_foo',
... '-center_foo-', 'right_foo-'])
s.str.strip()[0]
'spacious'

Rather than string matching, all combinations of the to_strip parameter's
characters are removed.

s.str.lstrip("-_")[1:]
1 left_foo
2 center_foo__-
3 right_foo-__
dtype: object

s.str.rstrip("-_")[1:]
1 __-left_foo
2 -__center_foo
3 right_foo
dtype: object

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

Docstring for "pandas.Series.str.strip" correct. :)

[datapythonista]

Really good work. Seems like we didn't coordinate well during the sprint, and it was duplicate work with @Cheukting who submitted #20863.

There is some great work in this PR that should be included in the final result. Can you please decide the PR we want to move forward with, and close the other.

[codecov]

Codecov Report

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

@@           Coverage Diff           @@
##           master   #20897   +/-   ##
=======================================
  Coverage   91.78%   91.78%           
=======================================
  Files         153      153           
  Lines       49341    49341           
=======================================
  Hits        45287    45287           
  Misses       4054     4054

Flag	Coverage Δ
#multiple	90.17% <ø> (ø)	⬆️
#single	41.94% <ø> (ø)	⬆️

Impacted Files	Coverage Δ
pandas/core/strings.py	98.34% <ø> (ø)	⬆️

---

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 28edd06...e598c7b. Read the comment docs.