docs: Clarify first_value usage in select vs aggregate (#1348)

* docs: Add warning to first_value about usage in select vs aggregate

Clarifies that aggregate functions like first_value must be used within .aggregate() and not .select(). Closes #1300.

* chore: remove temporary reproduction script

* Update all aggregate functions to have an example usage that is correct

---------

Co-authored-by: Tim Saucer <timsaucer@gmail.com>

Author: AdMub

python/datafusion/functions.py

@@ -1779,7 +1779,7 @@ def array_agg(
 
     For example::
 
-        df.select(array_agg(col("a"), order_by="b"))
+        df.aggregate([], array_agg(col("a"), order_by="b"))
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None
@@ -1941,7 +1941,7 @@ def median(
 
 
 def min(expression: Expr, filter: Expr | None = None) -> Expr:
-    """Returns the minimum value of the argument.
+    """Aggregate function that returns the minimum value of the argument.
 
     If using the builder functions described in ref:`_aggregation` this function ignores
     the options ``order_by``, ``null_treatment``, and ``distinct``.
@@ -2282,7 +2282,7 @@ def first_value(
 
     For example::
 
-        df.select(first_value(col("a"), order_by="ts"))
+        df.aggregate([], first_value(col("a"), order_by="ts"))
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None
@@ -2319,7 +2319,7 @@ def last_value(
 
     For example::
 
-        df.select(last_value(col("a"), order_by="ts"))
+        df.aggregate([], last_value(col("a"), order_by="ts"))
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None
@@ -2358,7 +2358,7 @@ def nth_value(
 
     For example::
 
-        df.select(nth_value(col("a"), 2, order_by="ts"))
+        df.aggregate([], nth_value(col("a"), 2, order_by="ts"))
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None
@@ -2843,7 +2843,7 @@ def string_agg(
 
     For example::
 
-        df.select(string_agg(col("a"), ",", order_by="b"))
+        df.aggregate([], string_agg(col("a"), ",", order_by="b"))
     """
     order_by_raw = sort_list_to_raw_sort_list(order_by)
     filter_raw = filter.expr if filter is not None else None