DOC: Update pandas.cut docstring
State: closed

Checklist for the pandas documentation sprint (ignore this if you are doing
an unrelated PR):

- [X ] PR title is "DOC: update the <your-function-or-method> docstring"
- [X ] The validation script passes: `scripts/validate_docstrings.py <your-function-or-method>`
- [X ] The PEP8 style check passes: `git diff upstream/master -u -- "*.py" | flake8 --diff`
- [X ] The html version looks good: `python doc/make.py --single <your-function-or-method>`
- [X ] It has been proofread on language by another sprint participant

Please include the output of the validation script below between the "```" ticks:

```
################################################################################
############################ Docstring (pandas.cut) ############################
################################################################################

Bin `x` and return data about the bin to which each `x` value belongs.

Splits `x` into the specified number of equal-width half-open bins.
Based on the parameters specified and the input, returns data about
the half-open bins to which each value of `x` belongs or the bins
themselves.
Use `cut` when you need to segment and sort data values into bins. This
function is also useful for going from a continuous variable to a
categorical variable. For example, `cut` could convert ages to groups
of age ranges.

Parameters
----------
x : array-like
    The input array to be binned. Must be 1-dimensional.
bins : int, sequence of scalars, or pandas.IntervalIndex
    If int, defines the number of equal-width bins in the range of `x`.
    The range of `x` is extended by .1% on each side to include the min or
    max values of `x`.
    If a sequence, defines the bin edges allowing for non-uniform width.
    No extension of the range of `x` is done.
right : bool, default 'True'
    Indicates whether the `bins` include the rightmost edge or not. If
    `right == True` (the default), then the `bins` [1,2,3,4] indicate
    (1,2], (2,3], (3,4].
labels : array or bool, optional
    Specifies the labels for the returned bins. Must be the same length as
    the resulting bins. If False, returns only integer indicators of the
    bins.
retbins : bool, default 'False'
    Whether to return the bins or not. Useful when bins is provided
    as a scalar.
precision : int, default '3'
    The precision at which to store and display the bins labels.
include_lowest : bool, default 'False'
    Whether the first interval should be left-inclusive or not.

Returns
-------
out : pandas.Categorical, Series, or ndarray
    An array-like object representing the respective bin for each value
    of `x`. The type depends on the value of `labels`.

    * True : returns a Series for Series `x` or a pandas.Categorical for
    pandas.Categorial `x`.

    * False : returns an ndarray of integers.
bins : numpy.ndarray of floats
    Returned when `retbins` is 'True'.

See Also
--------
qcut : Discretize variable into equal-sized buckets based on rank
    or based on sample quantiles.
pandas.Categorical : Represents a categorical variable in
    classic R / S-plus fashion.
Series : One-dimensional ndarray with axis labels (including time series).
pandas.IntervalIndex : Immutable Index implementing an ordered,
    sliceable set. IntervalIndex represents an Index of intervals that
    are all closed on the same side.

Notes
-----
Any NA values will be NA in the result. Out of bounds values will be NA in
the resulting pandas.Categorical object.

Examples
--------
>>> pd.cut(np.array([1,7,5,4,6,3]), 3)
... # doctest: +ELLIPSIS
[(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
Categories (3, interval[float64]): [(0.994, 3.0] < (3.0, 5.0] ...

>>> pd.cut(np.array([1,7,5,4,6,3]), 3, retbins=True)
... # doctest: +ELLIPSIS
([(0.994, 3.0], (5.0, 7.0], (3.0, 5.0], (3.0, 5.0], (5.0, 7.0], ...
Categories (3, interval[float64]): [(0.994, 3.0] < (3.0, 5.0] ...
array([0.994, 3.   , 5.   , 7.   ]))

>>> pd.cut(np.array([.2, 1.4, 2.5, 6.2, 9.7, 2.1]),
...        3, labels=["good", "medium", "bad"])
... # doctest: +SKIP
[good, good, good, medium, bad, good]
Categories (3, object): [good < medium < bad]

>>> pd.cut(np.ones(5, dtype='int64'), 4, labels=False)
array([1, 1, 1, 1, 1], dtype=int64)

>>> s = pd.Series(np.array([2,4,6,8,10]), index=['a', 'b', 'c', 'd', 'e'])
>>> pd.cut(s, 3)
... # doctest: +ELLIPSIS
a    (1.992, 4.667]
b    (1.992, 4.667]
c    (4.667, 7.333]
d     (7.333, 10.0]
e     (7.333, 10.0]
dtype: category
Categories (3, interval[float64]): [(1.992, 4.667] < (4.667, ...

################################################################################
################################## Validation ##################################
################################################################################

Docstring for "pandas.cut" correct. :)
```

Comment: Resubmitting https://github.com/pandas-dev/pandas/pull/20069 after a botched rebase. 


Labels:
name: Docs
name: Reshaping
description: Concat, Merge/Join, Stack/Unstack, Explode
name: Interval
description: Interval data type

Comments:
Did you already update according to my comments?
Nope, updating right now. :)
@jorisvandenbossche Updated based on your comments and added some more examples. I've also updated the validation script output in the description of the PR.
# [Codecov](https://codecov.io/gh/pandas-dev/pandas/pull/20104?src=pr&el=h1) Report
> Merging [#20104](https://codecov.io/gh/pandas-dev/pandas/pull/20104?src=pr&el=desc) into [master](https://codecov.io/gh/pandas-dev/pandas/commit/7169830040255c1073f99e2ee8817596a67b1cd5?src=pr&el=desc) will **increase** coverage by `0.02%`.
> The diff coverage is `n/a`.

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

```diff
@@            Coverage Diff             @@
##           master   #20104      +/-   ##
==========================================
+ Coverage    91.7%   91.72%   +0.02%     
==========================================
  Files         150      150              
  Lines       49165    49156       -9     
==========================================
+ Hits        45087    45090       +3     
+ Misses       4078     4066      -12
```

| Flag | Coverage Δ | |
|---|---|---|
| #multiple | `90.11% <ø> (+0.02%)` | :arrow_up: |
| #single | `41.85% <ø> (-0.02%)` | :arrow_down: |

| [Impacted Files](https://codecov.io/gh/pandas-dev/pandas/pull/20104?src=pr&el=tree) | Coverage Δ | |
|---|---|---|
| [pandas/core/reshape/tile.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvcmVzaGFwZS90aWxlLnB5) | `93.37% <ø> (ø)` | :arrow_up: |
| [pandas/plotting/\_core.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL3Bsb3R0aW5nL19jb3JlLnB5) | `82.23% <0%> (-0.04%)` | :arrow_down: |
| [pandas/core/indexes/datetimelike.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9kYXRldGltZWxpa2UucHk=) | `96.7% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/ops.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvb3BzLnB5) | `96.33% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/generic.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZ2VuZXJpYy5weQ==) | `95.84% <0%> (-0.02%)` | :arrow_down: |
| [pandas/core/window.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvd2luZG93LnB5) | `96.31% <0%> (ø)` | :arrow_up: |
| [pandas/core/frame.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvZnJhbWUucHk=) | `97.18% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexes/multi.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhlcy9tdWx0aS5weQ==) | `95.06% <0%> (ø)` | :arrow_up: |
| [pandas/core/strings.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvc3RyaW5ncy5weQ==) | `98.32% <0%> (ø)` | :arrow_up: |
| [pandas/core/indexing.py](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree#diff-cGFuZGFzL2NvcmUvaW5kZXhpbmcucHk=) | `93.02% <0%> (ø)` | :arrow_up: |
| ... and [8 more](https://codecov.io/gh/pandas-dev/pandas/pull/20104/diff?src=pr&el=tree-more) | |

------

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

Looks like some git issues @ikoevska. LMK if you need some help.
Did you have any changes in https://github.com/pandas-dev/pandas/pull/20104/commits/2dffb608b3949caf1b9d4a056c325deac6818390? If not, I think

```
git reset --hard d24c749b0 
git merge upstream/master
```

should do it. It'll throw away changes from that commit though.
Yep, I did a sync with the upstream and then a rebase on master and this happened. Suggestions how to fix it?

UPDATE: @TomAugspurger that fixed it, thanks so much!
Hello @ikoevska! Thanks for updating the PR.



Cheers ! There are no PEP8 issues in this Pull Request. :beers: 

##### Comment last updated on March 15, 2018 at 20:28 Hours UTC
@jreback Can you take a look at the latest changes and my comments? Thanks!