DOC: DataFrameGroupBy.idxmin() returns DataFrame, documentation says Serie (pandas-dev#60474)

* DOC: modify examples and return in docs

* DOC: fix examples

* DOC: unify

* Whitespace

* Pre commit

* Double line breaks

* DOC: finally rann pre commit

* Remove unused notebook

Author: Axeldnahcram

pandas/core/groupby/generic.py

@@ -1321,8 +1321,8 @@ def idxmin(self, skipna: bool = True) -> Series:
 
         Returns
         -------
-        Index
-            Label of the minimum value.
+        Series
+            Indexes of minima in each group.
 
         Raises
         ------
@@ -1374,8 +1374,8 @@ def idxmax(self, skipna: bool = True) -> Series:
 
         Returns
         -------
-        Index
-            Label of the maximum value.
+        Series
+            Indexes of maxima in each group.
 
         Raises
         ------
@@ -2512,8 +2512,8 @@ def idxmax(
 
         Returns
         -------
-        Series
-            Indexes of maxima in each group.
+        DataFrame
+            Indexes of maxima in each column according to the group.
 
         Raises
         ------
@@ -2523,6 +2523,7 @@ def idxmax(
         See Also
         --------
         Series.idxmax : Return index of the maximum element.
+        DataFrame.idxmax : Indexes of maxima along the specified axis.
 
         Notes
         -----
@@ -2536,6 +2537,7 @@ def idxmax(
         ...     {
         ...         "consumption": [10.51, 103.11, 55.48],
         ...         "co2_emissions": [37.2, 19.66, 1712],
+        ...         "food_type": ["meat", "plant", "meat"],
         ...     },
         ...     index=["Pork", "Wheat Products", "Beef"],
         ... )
@@ -2546,12 +2548,14 @@ def idxmax(
         Wheat Products       103.11         19.66
         Beef                  55.48       1712.00
 
-        By default, it returns the index for the maximum value in each column.
+        By default, it returns the index for the maximum value in each column
+        according to the group.
 
-        >>> df.idxmax()
-        consumption     Wheat Products
-        co2_emissions             Beef
-        dtype: object
+        >>> df.groupby("food_type").idxmax()
+                        consumption   co2_emissions
+        food_type
+        animal                 Beef            Beef
+        plant        Wheat Products  Wheat Products
         """
         return self._idxmax_idxmin("idxmax", numeric_only=numeric_only, skipna=skipna)
 
@@ -2574,8 +2578,8 @@ def idxmin(
 
         Returns
         -------
-        Series
-            Indexes of minima in each group.
+        DataFrame
+            Indexes of minima in each column according to the group.
 
         Raises
         ------
@@ -2585,6 +2589,7 @@ def idxmin(
         See Also
         --------
         Series.idxmin : Return index of the minimum element.
+        DataFrame.idxmin : Indexes of minima along the specified axis.
 
         Notes
         -----
@@ -2598,6 +2603,7 @@ def idxmin(
         ...     {
         ...         "consumption": [10.51, 103.11, 55.48],
         ...         "co2_emissions": [37.2, 19.66, 1712],
+        ...         "food_type": ["meat", "plant", "meat"],
         ...     },
         ...     index=["Pork", "Wheat Products", "Beef"],
         ... )
@@ -2608,12 +2614,14 @@ def idxmin(
         Wheat Products       103.11         19.66
         Beef                  55.48       1712.00
 
-        By default, it returns the index for the minimum value in each column.
+        By default, it returns the index for the minimum value in each column
+        according to the group.
 
-        >>> df.idxmin()
-        consumption                Pork
-        co2_emissions    Wheat Products
-        dtype: object
+        >>> df.groupby("food_type").idxmin()
+                        consumption   co2_emissions
+        food_type
+        animal                 Pork            Pork
+        plant        Wheat Products  Wheat Products
         """
         return self._idxmax_idxmin("idxmin", numeric_only=numeric_only, skipna=skipna)