DOC: Add regex example in str.split docstring
State: closed

- [x] closes #25296
- [x] tests added / passed
- [ ] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [ ] whatsnew entry

Adding the regex example in the `str.split()` documentation to make people aware of the need to escape special characters when using regular expressions as the pattern.

Error from docstring validation already exists in master's HEAD with no modifications. No additional error was introduced by the new docstring content.
Output of docstring validation:
```
$ python scripts/validate_docstrings.py pandas.Series.str.split

################################################################################
##################### Docstring (pandas.Series.str.split)  #####################
################################################################################

Split strings around given separator/delimiter.

Splits the string in the Series/Index from the beginning,
at the specified delimiter string. Equivalent to :meth:`str.split`.

Parameters
----------
pat : str, optional
    String or regular expression to split on.
    If not specified, split on whitespace.
n : int, default -1 (all)
    Limit number of splits in output.
    ``None``, 0 and -1 will be interpreted as return all splits.
expand : bool, default False
    Expand the splitted strings into separate columns.

    * If ``True``, return DataFrame/MultiIndex expanding dimensionality.
    * If ``False``, return Series/Index, containing lists of strings.

Returns
-------
Series, Index, DataFrame or MultiIndex
    Type matches caller unless ``expand=True`` (see Notes).

See Also
--------
 Series.str.split : Split strings around given separator/delimiter.
 Series.str.rsplit : Splits string around given separator/delimiter,
 starting from the right.
 Series.str.join : Join lists contained as elements in the Series/Index
 with passed delimiter.
 str.split : Standard library version for split.
 str.rsplit : Standard library version for rsplit.

Notes
-----
The handling of the `n` keyword depends on the number of found splits:

- If found splits > `n`,  make first `n` splits only
- If found splits <= `n`, make all splits
- If for a certain row the number of found splits < `n`,
  append `None` for padding up to `n` if ``expand=True``

If using ``expand=True``, Series and Index callers return DataFrame and
MultiIndex objects, respectively.

Examples
--------
>>> s = pd.Series(["this is a regular sentence",
"https://docs.python.org/3/tutorial/index.html", np.nan])

In the default setting, the string is split by whitespace.

>>> s.str.split()
0                   [this, is, a, regular, sentence]
1    [https://docs.python.org/3/tutorial/index.html]
2                                                NaN
dtype: object

Without the `n` parameter, the outputs of `rsplit` and `split`
are identical.

>>> s.str.rsplit()
0                   [this, is, a, regular, sentence]
1    [https://docs.python.org/3/tutorial/index.html]
2                                                NaN
dtype: object

The `n` parameter can be used to limit the number of splits on the
delimiter. The outputs of `split` and `rsplit` are different.

>>> s.str.split(n=2)
0                     [this, is, a regular sentence]
1    [https://docs.python.org/3/tutorial/index.html]
2                                                NaN
dtype: object

>>> s.str.rsplit(n=2)
0                     [this is a, regular, sentence]
1    [https://docs.python.org/3/tutorial/index.html]
2                                                NaN
dtype: object

The `pat` parameter can be used to split by other characters.

>>> s.str.split(pat = "/")
0                         [this is a regular sentence]
1    [https:, , docs.python.org, 3, tutorial, index...
2                                                  NaN
dtype: object

When using ``expand=True``, the split elements will expand out into
separate columns. If NaN is present, it is propagated throughout
the columns during the split.

>>> s.str.split(expand=True)
                                               0     1     2        3
0                                           this    is     a  regular
1  https://docs.python.org/3/tutorial/index.html  None  None     None
2                                            NaN   NaN   NaN      NaN 
             4
0     sentence
1         None
2          NaN

For slightly more complex use cases like splitting the html document name
from a url, a combination of parameter settings can be used.

>>> s.str.rsplit("/", n=1, expand=True)
                                    0           1
0          this is a regular sentence        None
1  https://docs.python.org/3/tutorial  index.html
2                                 NaN         NaN

Remember to escape special characters when explicitly using regular
expressions.

>>> s = pd.Series(["1+1=2", np.nan])

>>> s.str.split("\+|=", expand=True)
     0    1    2
0    1    1    2
1  NaN  NaN  NaN

################################################################################
################################## Validation ##################################
################################################################################

3 Errors found:
	Examples do not pass tests
	flake8 error: E902 TokenError: EOF in multi-line statement
	flake8 error: E999 SyntaxError: invalid syntax

################################################################################
################################### Doctests ###################################
################################################################################

**********************************************************************
Line 50, in pandas.Series.str.split
Failed example:
    s = pd.Series(["this is a regular sentence",
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[0]>", line 1
        s = pd.Series(["this is a regular sentence",
                                                   ^
    SyntaxError: unexpected EOF while parsing
**********************************************************************
Line 55, in pandas.Series.str.split
Failed example:
    s.str.split()
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[1]>", line 1, in <module>
        s.str.split()
    NameError: name 's' is not defined
**********************************************************************
Line 64, in pandas.Series.str.split
Failed example:
    s.str.rsplit()
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[2]>", line 1, in <module>
        s.str.rsplit()
    NameError: name 's' is not defined
**********************************************************************
Line 73, in pandas.Series.str.split
Failed example:
    s.str.split(n=2)
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[3]>", line 1, in <module>
        s.str.split(n=2)
    NameError: name 's' is not defined
**********************************************************************
Line 79, in pandas.Series.str.split
Failed example:
    s.str.rsplit(n=2)
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[4]>", line 1, in <module>
        s.str.rsplit(n=2)
    NameError: name 's' is not defined
**********************************************************************
Line 87, in pandas.Series.str.split
Failed example:
    s.str.split(pat = "/")
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[5]>", line 1, in <module>
        s.str.split(pat = "/")
    NameError: name 's' is not defined
**********************************************************************
Line 97, in pandas.Series.str.split
Failed example:
    s.str.split(expand=True)
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[6]>", line 1, in <module>
        s.str.split(expand=True)
    NameError: name 's' is not defined
**********************************************************************
Line 110, in pandas.Series.str.split
Failed example:
    s.str.rsplit("/", n=1, expand=True)
Exception raised:
    Traceback (most recent call last):
      File "/home/evan/anaconda3/envs/pandas/lib/python3.6/doctest.py", line 1330, in __run
        compileflags, 1), test.globs)
      File "<doctest pandas.Series.str.split[7]>", line 1, in <module>
        s.str.rsplit("/", n=1, expand=True)
    NameError: name 's' is not defined
```

Labels:
name: Docs

Comments:
Hello @Vandenn! 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-05-03 05:05:49 UTC
Update: Fixed the PEP8 issues with the force-pushed commits.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=h1) Report
> Merging [#26267](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/d49ebd4191887ebf35ebedc6c1a1608ce8e9505f?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #26267      +/-   ##
==========================================
- Coverage   91.98%   91.97%   -0.01%     
==========================================
  Files         175      175              
  Lines       52386    52386              
==========================================
- Hits        48186    48182       -4     
- Misses       4200     4204       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.52% <ø> (ø)` | :arrow_up: |
| #single | `40.71% <ø> (-0.15%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/26267/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.86% <ø> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/26267/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `78.94% <0%> (-10.53%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/26267/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.9% <0%> (-0.12%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26267?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/26267?src=pr&el=footer). Last update [d49ebd4...c6eac52](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=h1) Report
> Merging [#26267](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/0989339c2bb9ed583889ee86d584f4eb8c4362f9?src=pr&el=desc) will **decrease** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #26267      +/-   ##
==========================================
- Coverage   91.99%   91.98%   -0.01%     
==========================================
  Files         175      175              
  Lines       52379    52379              
==========================================
- Hits        48184    48180       -4     
- Misses       4195     4199       +4
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.53% <100%> (ø)` | :arrow_up: |
| #single | `40.72% <100%> (-0.15%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/26267/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.86% <100%> (ø)` | :arrow_up: |
| [pandas/io/gbq.py](https://codecov.io/gh/pandas-dev/pandas/pull/26267/diff?src=pr&el=tree#diff-cGFuZGFzL2lvL2dicS5weQ==) | `78.94% <0%> (-10.53%)` | :arrow_down: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/26267/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `96.9% <0%> (-0.12%)` | :arrow_down: |

------

[Continue to review full report at Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/26267?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/26267?src=pr&el=footer). Last update [0989339...ceb29a8](https://codecov.io/gh/pandas-dev/pandas/pull/26267?src=pr&el=lastupdated). Read the [comment docs](https://docs.codecov.io/docs/pull-request-comments).

Thanks @Vandenn !
Thanks @WillAyd and @gfyoung !