DOC: updated the Series.str.rsplit and Series.str.split docstrings
State: closed

- [ ] closes #xxxx
- [x] tests passed validate_docstrings.py
- [x] passes `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [x] rendered document looks ok 'python make.py --single pandas.Series.str.rsplit' and 'python make.py --single pandas.Series.str.split'



Labels:
name: Docs

Comments:
@datapythonista Finally got round to completing this after the PyData Pandas Sprint - let me know what you think ?
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/21026?src=pr&el=h1) Report
> Merging [#21026](https://codecov.io/gh/pandas-dev/pandas/pull/21026?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/028c9c0ef78878c9ef01570b47dd5211ef9d26ca?src=pr&el=desc) will **increase** coverage by `<.01%`.
> The diff coverage is `100%`.

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

```diff
@@            Coverage Diff             @@
##           master   #21026      +/-   ##
==========================================
+ Coverage    91.9%    91.9%   +<.01%     
==========================================
  Files         153      153              
  Lines       49549    49550       +1     
==========================================
+ Hits        45539    45540       +1     
  Misses       4010     4010
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.3% <100%> (ø)` | :arrow_up: |
| #single | `41.78% <100%> (ø)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/21026?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/21026/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.63% <100%> (ø)` | :arrow_up: |

------

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

I was taking a look, and I don't see a reason why `split` and `rsplit` should have different docstrings. I guess the docstrings are independent just because historical reasons. If you don't see a reason either, could you merge what you did with the existing `split` docstring please? You can take a look at `partition` or `rstrip` to see how to reuse a docstring in two methods.
@datapythonista Thanks. No I didn't find any reason for different docstrings, except the output of the examples being different. There were a few typos and whitespace issues that were corrected in the exisiting rstrip docstring - do you suggest I revert back to the format it was in before ? 
No, it's not about the format. In pandas, there are "normal" docstrings that are independent from the others, and are defined at the beginning of the function, like it was this case.

But then, there are methods or functions that are very similar, and the docstring is created once (usually at the beginning of the file), and then reused (by injecting it into the function) in more than one case.

So, originally, before you did any change, `split` and `rsplit` had different/independent docstrings. And you kept it this way, as expected. But what I'm proposing, is that instead of simply writing the docstring for `rsplit`, that you create a shared docstring with the best of what you did and the existing docstring of `split`, and then you reuse it for both functions. It may sound complex, but if you take a look at how this is done in `partition` and `rstrip` you'll see that it's very easy. And I think the final result will be much better, not having two separate docstrings that are (or should be) almost the same.

Let me know what do you think, and if you face any problem. Thanks!
Hello @ryankarlos! Thanks for updating the PR.

 - In the file [`pandas/core/strings.py`](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py), following are the PEP8 issues :

> [Line 2258:80](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py#L2258): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (110 > 79 characters)
> [Line 2268:80](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py#L2268): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (81 > 79 characters)
> [Line 2304:80](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py#L2304): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (83 > 79 characters)
> [Line 2305:80](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py#L2305): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (83 > 79 characters)
> [Line 2306:80](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py#L2306): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (83 > 79 characters)
> [Line 2307:80](https://github.com/pandas-dev/pandas/blob/390d351a4ab502d75dfced6ddcfb8176fe0052da/pandas/core/strings.py#L2307): [E501](https://duckduckgo.com/?q=pep8%20E501) line too long (83 > 79 characters)



##### Comment last updated on June 22, 2018 at 10:20 Hours UTC
@datapythonista Sorry for the delay. Oh ok I understand now, yes that makes sense. I have now updated the docstring to include a resuable docstring for rsplit and split like rpartition as you suggested. I have also adapted the original independent docstring so it only includes minimal information like partition and strip (excluding examples etc as I have added them in later). Let me know if it looks ok. 
Did you generate the docstrings to see if they are rendered ok? I may be wrong, but I think some stuff will appear duplicated.

Also, can you take a look at the PEP-8 errors in you code please? Seems like you have some tailing spaces and a line too long.
@datapythonista I have now corrected all whitespace issues and other PEP-8 errors. I rendered it and it looks ok - the examples were duplicated in both (since I had combined the rsplit and split examples for both functions. However, I have split them up so that rsplit examples will only show up in the rsplit doc and split examples in split doc. I have attached screenshots of what the sections of the docs look like.

![str rsplit_params](https://user-images.githubusercontent.com/16509490/41181083-713c4a72-6b68-11e8-9f0b-9f979c8dff5e.png)
![str rsplit_examples](https://user-images.githubusercontent.com/16509490/41181086-7309f174-6b68-11e8-9198-d8641ae760c4.png)
![str split_params](https://user-images.githubusercontent.com/16509490/41181438-7663eee6-6b69-11e8-8a4e-9c355b18633c.png)
![str split_examples](https://user-images.githubusercontent.com/16509490/41181387-3d0b379e-6b69-11e8-9021-fe43300548d0.png)



Looks quite good, but if I'm not mistaken, the docstrings under `str_split` and `str_rsplit` are not being used, are they? If that's right, I'd get rid of them.

Then, while your html looks great, creating separate examples and `See Also` options makes the code more complicated. What we've been doing in the other strings is in the `See Also` add both docstrings, even if they will self reference themselves. And for the examples, just show both methods in the same examples (so, a single set of examples that explain both `split` and `rsplit`).

It's not a big deal, but while the documentation is better the way you did it, we should try to keep the code simple too. I'd personally do it in the same way as in the other cases (you can take a look at the docstrings of the methods I mentioned before).
@datapythonista Yes, the docstrings under str_split and str_rsplit are not being used so i have got rid of them in the most recent commit.  Im a bit confused with what you meant by adding in both docstrings in the 'see also' bit. The docstring of the other methods like partition docstring just seems to be referencing the rpartition docstring in 'see also' and not self referencing partition as well.
Ive also now created a single set of examples that explain both split and rsplit. Let me know. 
Also, Im not too sure why one of the continuous integration check is failing....it was passing before ?

![str split1](https://user-images.githubusercontent.com/16509490/41197163-d0042ece-6c4b-11e8-86b7-6cf6d6f22a79.png)
![str split2](https://user-images.githubusercontent.com/16509490/41196835-484934f6-6c42-11e8-8e29-fe9c2c396aa0.png)
![str rsplit1](https://user-images.githubusercontent.com/16509490/41197160-b9cf2c94-6c4b-11e8-85f4-f8bcd4a46670.png)
![str rsplit2](https://user-images.githubusercontent.com/16509490/41196837-4b89e692-6c42-11e8-86f4-61d57d40e64a.png)

@datapythonista Sorry for the delay in gettting back. Thanks for the feedback - Ive updated the examples and 'See Also' section now.
@datapythonista thanks for the comments, makes sense - ill add those in. do you know why one of the jobs in the continuous-integration travis-ci checks may be failing - im thinking its due to some linting issues but can't figure out exactly what it is to make it pass ?  I can't find any similar issues raised by others
I'm not sure about the problem with travis. If it fails again after updating the PR, may be you can create an environment with Python 3.5 and run `lint.sh` manually? I don't see much information in travis logs, so hopefully it can be reproduced locally.
@datapythonista just updated the PR. So what I did in the examples was to only include rsplit in one example (changing n with path separator) and the rest with just split. Also included the default split as the first example.  At the moment it will just show up as s.str.split() for both docs - i don't know if it would look better to have it as s.str.rsplit() for the rsplit documentation - of course the output doesn't make a difference but i was just thinking it may look odd if someone sees split as the default first example under rsplit doc. If its not  a big deal we can leave it like it is.
@datapythonista Updated PR with changes to examples added in. Here's screenshots of what the examples look like in the rendered html - it think its looking a lot more complete now.

![examples_1](https://user-images.githubusercontent.com/16509490/41751642-5dd6cbc2-75ba-11e8-8e98-7bb513e44e4e.png)

![examples_2](https://user-images.githubusercontent.com/16509490/41751645-6162923a-75ba-11e8-9d65-926158641426.png)

@ryankarlos have some linting issues:
```
(pandas) bash-3.2$ git diff master --name-only -- "*.py" | grep "pandas" | xargs flake8
git diff master --name-only -- "*.py" | grep "pandas" | xargs flake8
pandas/core/strings.py:1366:1: W293 blank line contains whitespace
pandas/core/strings.py:2237:73: W291 trailing whitespace
pandas/core/strings.py:2239:76: W291 trailing whitespace
pandas/core/strings.py:2240:28: W291 trailing whitespace
pandas/core/strings.py:2258:80: E501 line too long (110 > 79 characters)
pandas/core/strings.py:2258:111: W291 trailing whitespace
pandas/core/strings.py:2268:80: E501 line too long (81 > 79 characters)
pandas/core/strings.py:2279:25: W291 trailing whitespace
pandas/core/strings.py:2291:66: W291 trailing whitespace
pandas/core/strings.py:2300:69: W291 trailing whitespace
pandas/core/strings.py:2304:80: E501 line too long (83 > 79 characters)
pandas/core/strings.py:2305:80: E501 line too long (83 > 79 characters)
pandas/core/strings.py:2305:84: W291 trailing whitespace
pandas/core/strings.py:2306:80: E501 line too long (83 > 79 characters)
pandas/core/strings.py:2307:80: E501 line too long (83 > 79 characters)
pandas/core/strings.py:2322:9: E123 closing bracket does not match indentation of opening bracket's line
pandas/core/strings.py:2330:9: E123 closing bracket does not match indentation of opening bracket's line
pandas/core/strings.py:2330:11: W291 trailing whitespace
```

i fixed some of those.
@jreback ahh sorry - I fixed these now  but Im getting another weird error I haven't seen before  when running validate_docstrings.py - it was working ok previously. Seems to be some class inheritance issue in one of the other recently updated files but not exactly sure ? Also, same errors when trying to render the html.

Ryans-MacBook-Air:doc ryannazareth$ python ../scripts/validate_docstrings.py pandas.Series.str.rsplit
Traceback (most recent call last):
  File "../scripts/validate_docstrings.py", line 37, in <module>
    import pandas
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/__init__.py", line 42, in <module>
    from pandas.core.api import *
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/core/api.py", line 10, in <module>
    from pandas.core.groupby.groupby import Grouper
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/core/groupby/__init__.py", line 2, in <module>
    from pandas.core.groupby.groupby import (
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/core/groupby/groupby.py", line 46, in <module>
    from pandas.core.index import (Index, MultiIndex,
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/core/index.py", line 2, in <module>
    from pandas.core.indexes.api import *
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/core/indexes/api.py", line 4, in <module>
    from pandas.core.indexes.base import (Index,
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/core/indexes/base.py", line 7, in <module>
    from pandas._libs import (lib, index as libindex, tslib as libts,
  File "pandas/_libs/index.pyx", line 28, in init pandas._libs.index
  File "pandas/_libs/tslibs/period.pyx", line 59, in init pandas._libs.tslibs.period
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/tseries/offsets.py", line 2331, in <module>
    offset=BDay(), time_rule=None):
  File "/Users/ryannazareth/Documents/PyData_Conference_2018/Pandas_Sprint/pandas/pandas/tseries/offsets.py", line 485, in __init__
    BaseOffset.__init__(self, n, normalize)
TypeError: object.__init__() takes no parameters
@ryankarlos I think the problem is with the C extensions. I'd get the last version from master, and then build the extenstions again:

```
git fetch upstream
git merge upstream/master
python setup.py build_ext --inplace -j4
```
@datapythonista Thanks that seemed to do the trick ! 
@jreback  PR updated with fixed linting issues 
thanks @ryankarlos