docs: Add documentation for LazyGroupBy (#1423)

* add documentation for lazygroupby

* update index

docs/api-reference/index.md

@@ -8,6 +8,7 @@
 - [narwhals.Expr.name](expr_name.md)
 - [narwhals.Expr.str](expr_str.md)
 - [narwhals.GroupBy](group_by.md)
+- [narwhals.LazyGroupBy](lazy_group_by.md)
 - [narwhals.LazyFrame](lazyframe.md)
 - [narwhals.Schema](schema.md)
 - [narwhals.Series](series.md)

docs/api-reference/lazy_group_by.md

@@ -0,0 +1,9 @@
+# `narwhals.LazyGroupBy`
+
+::: narwhals.group_by.LazyGroupBy
+    handler: python
+    options:
+      members:
+        - agg
+      show_source: false
+      show_bases: false

mkdocs.yml

@@ -37,6 +37,7 @@ nav:
     - api-reference/expr_name.md
     - api-reference/expr_str.md
     - api-reference/group_by.md
+    - api-reference/lazy_group_by.md
     - api-reference/lazyframe.md
     - api-reference/schema.md
     - api-reference/series.md

narwhals/group_by.py

@@ -132,6 +132,69 @@ def __init__(self, df: LazyFrameT, *keys: str, drop_null_keys: bool) -> None:
     def agg(
         self, *aggs: IntoExpr | Iterable[IntoExpr], **named_aggs: IntoExpr
     ) -> LazyFrameT:
+        """Compute aggregations for each group of a group by operation.
+
+        If a library does not support lazy execution, then this is a no-op.
+
+        Arguments:
+            aggs: Aggregations to compute for each group of the group by operation,
+                specified as positional arguments.
+            named_aggs: Additional aggregations, specified as keyword arguments.
+
+        Returns:
+            A new LazyFrame.
+
+        Examples:
+            Group by one column or by multiple columns and call `agg` to compute
+            the grouped sum of another column.
+
+            >>> import polars as pl
+            >>> import narwhals as nw
+            >>> from narwhals.typing import IntoFrameT
+            >>> lf_pl = pl.LazyFrame(
+            ...     {
+            ...         "a": ["a", "b", "a", "b", "c"],
+            ...         "b": [1, 2, 1, 3, 3],
+            ...         "c": [5, 4, 3, 2, 1],
+            ...     }
+            ... )
+
+            We define library agnostic functions:
+
+            >>> def agnostic_func_one_col(lf_native: IntoFrameT) -> IntoFrameT:
+            ...     lf = nw.from_native(lf_native)
+            ...     return nw.to_native(lf.group_by("a").agg(nw.col("b").sum()).sort("a"))
+
+            >>> def agnostic_func_mult_col(lf_native: IntoFrameT) -> IntoFrameT:
+            ...     lf = nw.from_native(lf_native)
+            ...     return nw.to_native(lf.group_by("a", "b").agg(nw.sum("c")).sort("a", "b"))
+
+            We can then pass a lazy frame and materialise it with `collect`:
+
+            >>> agnostic_func_one_col(lf_pl).collect()
+            shape: (3, 2)
+            ┌─────┬─────┐
+            │ a   ┆ b   │
+            │ --- ┆ --- │
+            │ str ┆ i64 │
+            ╞═════╪═════╡
+            │ a   ┆ 2   │
+            │ b   ┆ 5   │
+            │ c   ┆ 3   │
+            └─────┴─────┘
+            >>> agnostic_func_mult_col(lf_pl).collect()
+            shape: (4, 3)
+            ┌─────┬─────┬─────┐
+            │ a   ┆ b   ┆ c   │
+            │ --- ┆ --- ┆ --- │
+            │ str ┆ i64 ┆ i64 │
+            ╞═════╪═════╪═════╡
+            │ a   ┆ 1   ┆ 8   │
+            │ b   ┆ 2   ┆ 4   │
+            │ b   ┆ 3   ┆ 2   │
+            │ c   ┆ 3   ┆ 1   │
+            └─────┴─────┴─────┘
+        """
         aggs, named_aggs = self._df._flatten_and_extract(*aggs, **named_aggs)
         return self._df._from_compliant_dataframe(  # type: ignore[return-value]
             self._grouped.agg(*aggs, **named_aggs),