DOC: update NDFrame.squeeze docstring
State: closed

## Series.squeeze and DataFrame.squeeze are inherited from NDFrame 

- [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.DataFrame.squeeze) #####################
################################################################################

Squeeze 1 dimensional axis objects into scalars.

If the given axis consists of one dimensional objects, they are turned
into scalars. In case no axis is specified, all axes are subject to
squeezing. In any case, objects in axes that can't be squeezed are
left unchanged.

Parameters
----------
axis : integer or string, optional
    A specific axis to squeeze.

    .. versionadded:: 0.20.0

Returns
-------
DataFrame, Series or scalar
    The projection after squeezing axis.

See Also
--------
Series.iloc : Integer-location based indexing for selecting scalars
DataFrame.iloc : Integer-location based indexing for selecting Series

Examples
--------
>>> primes = pd.Series([2, 3, 5, 7])

Slicing might produce a Series with a single value:

>>> even_primes = primes[primes % 2 == 0]
>>> even_primes
0    2
dtype: int64
>>> even_primes.squeeze()
2

Squeezing objects with more than 1 dimension does nothing:

>>> odd_primes = primes[primes % 2 == 1]
>>> odd_primes
1    3
2    5
3    7
dtype: int64
>>> odd_primes.squeeze()
1    3
2    5
3    7
dtype: int64

Squeezing is even more effective when used with DataFrames.

>>> df = pd.DataFrame([[1,2], [3, 4]], columns=['a', 'b'])
>>> df
   a  b
0  1  2
1  3  4

Slicing a single column will produce a DataFrame with one of the
axis having only 1 dimension:

>>> df_a = df[['a']]
>>> df_a
   a
0  1
1  3

Objects along the column are 1 dimensional, so they can be squeezed
into scalars:

>>> df_a.squeeze('columns')
0    1
1    3
Name: a, dtype: int64

Slicing a single row from a single column will produce a single
scalar DataFrame:

>>> df_0a = df[['a']].iloc[[0]]
>>> df_0a
   a
0  1

Squeezing along the rows produces a single scalar Series:

>>> df_0a.squeeze('rows')
a    1
Name: 0, dtype: int64

Squeezing all axes wil project directly into a scalar:

>>> df_0a.squeeze()
1

################################################################################
################################## Validation ##################################
################################################################################

Errors found:
        Errors in parameters section
                Parameter "axis" description should finish with "."
```

> If the validation script still gives errors, but you think there is a good reason
to deviate in this case (and there are certainly such cases), please state this
explicitly.

The `.. versionadded` rst macro already adds the dot, so I can't just put another one after it.

Labels:
name: Docs

Comments:
Updated, if anyone wants to take a look.  Merging tomorrow otherwise.

I went with @datapythonista's suggestion on how to phrase the extended summary. Pandas only has to worry about `n <= 2`, so let's take advantage of that in the docs.

I was going to implement a few of the discussed changes next Saturday, but you can merge this one and if I actually get to it I'll make a new PR.
No rush. Feel free to pull my changes and push them here.

On Wed, Mar 14, 2018 at 3:29 PM, Victor Villas <notifications@github.com>
wrote:

> I was going to implement a few of the discussed changes next Saturday, but
> you can merge this one and if I actually get to it I'll make a new PR.
>
> —
> You are receiving this because you commented.
> Reply to this email directly, view it on GitHub
> <https://github.com/pandas-dev/pandas/pull/20269#issuecomment-373163654>,
> or mute the thread
> <https://github.com/notifications/unsubscribe-auth/ABQHIu1UbiAJG66_eXrMOqK-xjNAQ8WMks5teX2VgaJpZM4Slhl1>
> .
>

Merging this as-is, since it looks like this is good.

@villasv : Thanks! Happy to take any additional updates as a separate PR, if you're still interested in implementing additional changes.