DOC: Fixed timedelta docstring and examples
State: closed

- [x] closes #23248
- [x] tests added / passed
- [x] passes `git diff upstream/master --name-only -- "*.py" | grep "pandas/" | xargs flake8`
- [x] passes `python scripts/validate_docstrings.py pandas.to_timedelta`


Labels:
name: Docs
name: Timedelta
description: Timedelta data type

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

 - There are no PEP8 issues in the file [`pandas/core/tools/timedeltas.py`](https://github.com/ryankarlos/pandas/blob/0c5129f79dae0d439fc29e8678347bdd6b1df9ec/pandas/core/tools/timedeltas.py) !



##### Comment last updated on October 27, 2018 at 13:50 Hours UTC
I've added in a few examples to illustrate 'M' and 'Y' outputs along with generating new columns in a dataframe using timedelta. Also corrected some linting issues and added a better summary. Any feedback would be welcome.
Travis failing in feather --- ive seen other PRs having the same problem - not sure why it is ?
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/23259?src=pr&el=h1) Report
> Merging [#23259](https://codecov.io/gh/pandas-dev/pandas/pull/23259?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/deb7b4d5003b939f47e525bcdaceeea48622a73a?src=pr&el=desc) will **not change** coverage.
> The diff coverage is `n/a`.

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

```diff
@@           Coverage Diff           @@
##           master   #23259   +/-   ##
=======================================
  Coverage   92.28%   92.28%           
=======================================
  Files         161      161           
  Lines       51451    51451           
=======================================
  Hits        47483    47483           
  Misses       3968     3968
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.68% <ø> (ø)` | :arrow_up: |
| #single | `42.31% <ø> (+0.03%)` | :arrow_up: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/23259?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/tools/timedeltas.py](https://codecov.io/gh/pandas-dev/pandas/pull/23259/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvdG9vbHMvdGltZWRlbHRhcy5weQ==) | `98.03% <ø> (ø)` | :arrow_up: |

------

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

cc @datapythonista if you could have a look.
@mroeschke  I haven't added the notes section for deprecated units yet - i was working concurrently on #23264 so  wasn't sure if i should add that in before finishing that 
@datapythonista Thanks for the review. Added changes. Also rendered the docstring below:

![screen shot 2018-10-27 at 00 40 25](https://user-images.githubusercontent.com/16509490/47596871-731ba400-d981-11e8-81c7-a87ab6db9068.png)




@datapythonista Thanks, added an update. Im working concurrently on a related PR #23264  -- not sure if i should add the notes section on deprecated units here or in that PR ? 
@datapythonista done :)

![screen shot 2018-10-27 at 15 05 57](https://user-images.githubusercontent.com/16509490/47605113-14ded780-d9fa-11e8-99bf-a25ec965b504.png)

@datapythonista There is a now a conflict with the most recent merge #23439 - with more additions in the units parameters.  Should I revert to the version we have in this - or do you prefer to include all those units ('Y', 'M' shouldn't be in there for eg ?). Let me know and I can fix.
Unlucky this was not merged earlier.

You need to fix the conflict in a way that you get the lastest changes (from the conflicting PR in this case), and you make any fixes to that.

This PR is a diff of what you have and master, if you take your changes, you'll be deleting the work in that PR here.

I'm not sure of how the long set of units in that PR renders. If it doesn't render correctly, you can fix it here (instead of having the units in the type, just say `str` and then you show the units as a list in the description).
@datapythonista ok thanks - ill fetch the latest changes from master - so is it ok for me to list the units as the short format `(D, h, m, s, ms, us, ns)` in the description if the long format looks odd on rendering. Is expanding on all the different unit formats necessary ? 
Yes, if they were added that's for a reason. Avoid changing the content unless you really know what you're doing. But make the format look as good as possible. And in this case, I'm not sure how sphinx handles multilines in the types, we had problems with that in the past, so may be the current format is displayed broken.
@datapythonista Ive fixed the merge conflict to include changes from upstream. The units were not rendering properly when including in the type (the format was getting broken after the first line) so I shifted it to the description as you had suggested.


![screen shot 2018-11-13 at 00 10 16](https://user-images.githubusercontent.com/16509490/48382397-da9f5680-e6d8-11e8-89da-e94dd9e6654e.png)

@datapythonista over to you. merge when satisfied.
Thanks for fixing this @ryankarlos