docs(python): Add docstring examples for datetimes (#13161) (#15804)

Co-authored-by: Ned Western <Ned.Western@aemo.com.au>

py-polars/polars/functions/as_datatype.py

@@ -81,6 +81,38 @@ def datetime_(
     -------
     Expr
         Expression of data type :class:`Datetime`.
+
+    Examples
+    --------
+    >>> df = pl.DataFrame(
+    ...     {
+    ...         "month": [1, 2, 3],
+    ...         "day": [4, 5, 6],
+    ...         "hour": [12, 13, 14],
+    ...         "minute": [15, 30, 45],
+    ...     }
+    ... )
+
+    >>> df.with_columns(
+    ...     pl.datetime(
+    ...         2024,
+    ...         pl.col("month"),
+    ...         pl.col("day"),
+    ...         pl.col("hour"),
+    ...         pl.col("minute"),
+    ...         time_zone="Australia/Sydney",
+    ...     )
+    ... )
+    shape: (3, 5)
+    ┌───────┬─────┬──────┬────────┬────────────────────────────────┐
+    │ month ┆ day ┆ hour ┆ minute ┆ datetime                       │
+    │ ---   ┆ --- ┆ ---  ┆ ---    ┆ ---                            │
+    │ i64   ┆ i64 ┆ i64  ┆ i64    ┆ datetime[μs, Australia/Sydney] │
+    ╞═══════╪═════╪══════╪════════╪════════════════════════════════╡
+    │ 1     ┆ 4   ┆ 12   ┆ 15     ┆ 2024-01-04 12:15:00 AEDT       │
+    │ 2     ┆ 5   ┆ 13   ┆ 30     ┆ 2024-02-05 13:30:00 AEDT       │
+    │ 3     ┆ 6   ┆ 14   ┆ 45     ┆ 2024-03-06 14:45:00 AEDT       │
+    └───────┴─────┴──────┴────────┴────────────────────────────────┘
     """
     ambiguous = parse_as_expression(
         rename_use_earliest_to_ambiguous(use_earliest, ambiguous), str_as_lit=True
@@ -135,6 +167,27 @@ def date_(
     -------
     Expr
         Expression of data type :class:`Date`.
+
+    Examples
+    --------
+    >>> df = pl.DataFrame(
+    ...     {
+    ...         "month": [1, 2, 3],
+    ...         "day": [4, 5, 6],
+    ...     }
+    ... )
+
+    >>> df.with_columns(pl.date(2024, pl.col("month"), pl.col("day")))
+    shape: (3, 3)
+    ┌───────┬─────┬────────────┐
+    │ month ┆ day ┆ date       │
+    │ ---   ┆ --- ┆ ---        │
+    │ i64   ┆ i64 ┆ date       │
+    ╞═══════╪═════╪════════════╡
+    │ 1     ┆ 4   ┆ 2024-01-04 │
+    │ 2     ┆ 5   ┆ 2024-02-05 │
+    │ 3     ┆ 6   ┆ 2024-03-06 │
+    └───────┴─────┴────────────┘
     """
     return datetime_(year, month, day).cast(Date).alias("date")
 
@@ -163,6 +216,27 @@ def time_(
     -------
     Expr
         Expression of data type :class:`Date`.
+
+    Examples
+    --------
+    >>> df = pl.DataFrame(
+    ...     {
+    ...         "hour": [12, 13, 14],
+    ...         "minute": [15, 30, 45],
+    ...     }
+    ... )
+
+    >>> df.with_columns(pl.time(pl.col("hour"), pl.col("minute")))
+    shape: (3, 3)
+    ┌──────┬────────┬──────────┐
+    │ hour ┆ minute ┆ time     │
+    │ ---  ┆ ---    ┆ ---      │
+    │ i64  ┆ i64    ┆ time     │
+    ╞══════╪════════╪══════════╡
+    │ 12   ┆ 15     ┆ 12:15:00 │
+    │ 13   ┆ 30     ┆ 13:30:00 │
+    │ 14   ┆ 45     ┆ 14:45:00 │
+    └──────┴────────┴──────────┘
     """
     epoch_start = (1970, 1, 1)
     return (