Deprecate squeeze in GroupBy. (#8507)

* Deprecate `squeeze` in GroupBy.

Closes #2157

* silence warnings

* better warning

* Fix first, last

* Set squeeze=None for Dataset too

* Update xarray/tests/test_groupby.py

* Test one more warning

* Reduce more warnings

* fix whats-new

* Fix docs

* Fix generator for aggregations

* Fix typing

* Add tests for #8263

* minimize test mods

* Silence more warnings

* Apply suggestions from code review

Co-authored-by: Michael Niklas  <mick.niklas@gmail.com>

* [pre-commit.ci] auto fixes from pre-commit.com hooks

for more information, see https://pre-commit.ci

* Don't skip for resampling

---------

Co-authored-by: Michael Niklas <mick.niklas@gmail.com>
Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>

doc/user-guide/groupby.rst

@@ -177,28 +177,18 @@ This last line is roughly equivalent to the following::
         results.append(group - alt.sel(letters=label))
     xr.concat(results, dim='x')
 
-Squeezing
-~~~~~~~~~
+Iterating and Squeezing
+~~~~~~~~~~~~~~~~~~~~~~~
 
-When grouping over a dimension, you can control whether the dimension is
-squeezed out or if it should remain with length one on each group by using
-the ``squeeze`` parameter:
-
-.. ipython:: python
-
-    next(iter(arr.groupby("x")))
+Previously, Xarray defaulted to squeezing out dimensions of size one when iterating over
+a GroupBy object. This behaviour is being removed.
+You can always squeeze explicitly later with the Dataset or DataArray
+:py:meth:`~xarray.DataArray.squeeze` methods.
 
 .. ipython:: python
 
     next(iter(arr.groupby("x", squeeze=False)))
 
-Although xarray will attempt to automatically
-:py:attr:`~xarray.DataArray.transpose` dimensions back into their original order
-when you use apply, it is sometimes useful to set ``squeeze=False`` to
-guarantee that all original dimensions remain unchanged.
-
-You can always squeeze explicitly later with the Dataset or DataArray
-:py:meth:`~xarray.DataArray.squeeze` methods.
 
 .. _groupby.multidim:
 

doc/whats-new.rst

@@ -57,7 +57,8 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
-
+- The `squeeze` kwarg to GroupBy is now deprecated. (:issue:`2157`, :pull:`8507`)
+  By `Deepak Cherian <https://github.com/dcherian>`_.
 
 Bug fixes
 ~~~~~~~~~
@@ -141,7 +142,6 @@ Breaking changes
 
 Deprecations
 ~~~~~~~~~~~~
-
 - As part of an effort to standardize the API, we're renaming the ``dims``
   keyword arg to ``dim`` for the minority of functions which current use
   ``dims``. This started with :py:func:`xarray.dot` & :py:meth:`DataArray.dot`