docs(examples): add Value.asc and Value.desc examples (#10515)

## Description of changes

Sets up examples, parameter, return information, and links to respective
top level equivalent functions for
[Value.asc](https://ibis-project.org/reference/expression-generic#ibis.expr.types.generic.Value.asc)
and
[Value.desc](https://ibis-project.org/reference/expression-generic#ibis.expr.types.generic.Value.desc).

Fixes small typo with weather -> whether.

Author: IndexSeek

ibis/expr/api.py

@@ -591,7 +591,7 @@ def desc(expr: ir.Column | str, nulls_first: bool = False) -> ir.Value:
     expr
         The expression or column name to use for sorting
     nulls_first
-        Bool to indicate weather to put NULL values first or not.
+        Bool to indicate whether to put NULL values first or not.
 
     See Also
     --------
@@ -632,7 +632,7 @@ def asc(expr: ir.Column | str, nulls_first: bool = False) -> ir.Value:
     expr
         The expression or column name to use for sorting
     nulls_first
-        Bool to indicate weather to put NULL values first or not.
+        Bool to indicate whether to put NULL values first or not.
 
     See Also
     --------

ibis/expr/types/generic.py

@@ -1192,11 +1192,97 @@ def __lt__(self, other: Value) -> ir.BooleanValue:
         return _binop(ops.Less, self, other)
 
     def asc(self, nulls_first: bool = False) -> ir.Value:
-        """Sort an expression ascending."""
+        """Sort an expression ascending.
+
+        Parameters
+        ----------
+        nulls_first
+            Whether to sort `NULL` values first
+
+        Returns
+        -------
+        Value
+            Sorted expression
+
+        See Also
+        --------
+        [`ibis.asc()`](./expression-generic.qmd#ibis.asc)
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable({"a": [1, 2, 3, None]})
+        >>> t.order_by(t.a.asc())
+        ┏━━━━━━━━━┓
+        ┃ a       ┃
+        ┡━━━━━━━━━┩
+        │ float64 │
+        ├─────────┤
+        │     1.0 │
+        │     2.0 │
+        │     3.0 │
+        │    NULL │
+        └─────────┘
+        >>> t.order_by(t.a.asc(nulls_first=True))
+        ┏━━━━━━━━━┓
+        ┃ a       ┃
+        ┡━━━━━━━━━┩
+        │ float64 │
+        ├─────────┤
+        │    NULL │
+        │     1.0 │
+        │     2.0 │
+        │     3.0 │
+        └─────────┘
+        """
         return ops.SortKey(self, ascending=True, nulls_first=nulls_first).to_expr()
 
     def desc(self, nulls_first: bool = False) -> ir.Value:
-        """Sort an expression descending."""
+        """Sort an expression descending.
+
+        Parameters
+        ----------
+        nulls_first
+            Whether to sort `NULL` values first.
+
+        Returns
+        -------
+        Value
+            Sorted expression
+
+        See Also
+        --------
+        [`ibis.desc()`](./expression-generic.qmd#ibis.desc)
+
+        Examples
+        --------
+        >>> import ibis
+        >>> ibis.options.interactive = True
+        >>> t = ibis.memtable({"a": [1, 2, 3, None]})
+        >>> t.order_by(t.a.desc())
+        ┏━━━━━━━━━┓
+        ┃ a       ┃
+        ┡━━━━━━━━━┩
+        │ float64 │
+        ├─────────┤
+        │     3.0 │
+        │     2.0 │
+        │     1.0 │
+        │    NULL │
+        └─────────┘
+        >>> t.order_by(t.a.desc(nulls_first=True))
+        ┏━━━━━━━━━┓
+        ┃ a       ┃
+        ┡━━━━━━━━━┩
+        │ float64 │
+        ├─────────┤
+        │    NULL │
+        │     3.0 │
+        │     2.0 │
+        │     1.0 │
+        └─────────┘
+        """
         return ops.SortKey(self, ascending=False, nulls_first=nulls_first).to_expr()
 
     def to_pandas(self, **kwargs) -> pd.Series: