docs: add examples to the documentation (#618)

* Improve documentation for `_spanners.py`

* Improve documentation for `_modify_rows.py`

* Improve documentation for `_formats_vals.py`

* Update `tab_spanner()` docs based on review feedback

great_tables/_formats_vals.py

@@ -143,6 +143,14 @@ def val_fmt_number(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_number([0.325, 777000], decimals=2)
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -236,6 +244,14 @@ def val_fmt_integer(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_integer([100000.1, 2000000000.2], use_seps=False)
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -354,6 +370,14 @@ def val_fmt_scientific(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_scientific([123456, 0.425639], decimals=2)
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -474,6 +498,14 @@ def val_fmt_percent(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_percent([0.3, 0.926132], decimals=2)
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -599,6 +631,14 @@ def val_fmt_currency(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_currency([1.02, 3.46], decimals=3)
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -652,6 +692,14 @@ def val_fmt_roman(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_roman([3, 5])
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -754,6 +802,14 @@ def val_fmt_bytes(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_bytes([123.45, 3615844.256], standard="decimal")
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -841,6 +897,14 @@ def val_fmt_date(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_date(["2025-01-01", "2025-01-02"], date_style="month_day_year")
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -907,6 +971,14 @@ def val_fmt_time(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    vals.fmt_time(["05:32:17", "13:01:02"], time_style="h_m_s_p")
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -940,6 +1012,29 @@ def val_fmt_markdown(
     -------
     list[str]
         A list of formatted values is returned.
+
+    Examples
+    --------
+    ```{python}
+    from great_tables import vals
+
+    text_1 = \"""
+    ### This is Markdown.
+
+    Markdown’s syntax is comprised entirely of
+    punctuation characters, which punctuation
+    characters have been carefully chosen so as
+    to look like what they mean... assuming
+    you’ve ever used email.
+    \"""
+
+    text_2 = \"""
+    Info on Markdown syntax can be found
+    [here](https://daringfireball.net/projects/markdown/).
+    \"""
+
+    vals.fmt_markdown([text_1, text_2])
+    ```
     """
 
     gt_obj: GTData = _make_one_col_table(vals=x)
@@ -1000,6 +1095,11 @@ def val_fmt_image(
     -------
     list[str]
         A list of formatted values is returned.
+
+    See Also
+    --------
+    Check out our blog post, [Rendering images anywhere in Great Tables](https://posit-dev.github.io/great-tables/blog/rendering-images/),
+    which walks through how to use `vals.fmt_image()`.
     """
     gt_obj: GTData = _make_one_col_table(vals=x)
 

great_tables/_modify_rows.py

@@ -43,6 +43,12 @@ def tab_stub(
     groupname_col:
         The column to use for group names. By default no group names added.
 
+    Returns
+    -------
+    GT
+        The GT object is returned. This is the same object that the method is called on so that we
+        can facilitate method chaining.
+
     Examples
     --------
 
@@ -94,9 +100,51 @@ def tab_stub(
 def with_locale(self: GTSelf, locale: str | None = None) -> GTSelf:
     """Set a column to be the default locale.
 
-    Setting a default locale affects formatters like .fmt_number, and .fmt_date,
+    Setting a default locale affects formatters like `fmt_number()`, and `fmt_date()`,
     by having them default to locale-specific features (e.g. representing one thousand
     as 1.000,00)
+
+    Parameters
+    ----------
+    locale
+        An optional locale identifier that can be used for formatting values according the locale's
+        rules. Examples include `"en"` for English (United States) and `"fr"` for French (France).
+
+    Returns
+    -------
+    GT
+        The GT object is returned. This is the same object that the method is called on so that we
+        can facilitate method chaining.
+
+    Examples
+    --------
+    Let's create a table and set its `locale=` to `"ja"` for Japan. Then, we call `fmt_currency()`
+    to format the `"currency"` column. Since we didn't specify a `locale=` for `fmt_currency()`,
+    it will adopt the globally set `"ja"` locale.
+
+    ```{python}
+    from great_tables import GT, exibble
+
+
+    (
+        GT(exibble)
+        .with_locale("ja")
+        .fmt_currency(
+            columns="currency",
+            decimals=3,
+            use_seps=False
+        )
+    )
+    ```
+    **Great Tables** internally supports many locale options. You can find the available locales in
+    the following table:
+
+    ```{python}
+    from great_tables.data import __x_locales
+
+    columns = ["locale", "lang_name", "lang_desc", "territory_name", "territory_desc"]
+    GT(__x_locales.loc[:, columns]).cols_align("right")
+    ```
     """
 
     return self._replace(_locale=Locale(locale))
@@ -106,5 +154,27 @@ def with_id(self: GTSelf, id: str | None = None) -> GTSelf:
     """Set the id for this table.
 
     Note that this is a shortcut for the `table_id=` argument in `GT.tab_options()`.
+
+    Parameters
+    ----------
+    id
+        By default (with `None`) the table ID will be a random, ten-letter string as generated
+        through internal use of the `random_id()` function. A custom table ID can be used here by
+        providing a string.
+
+    Returns
+    -------
+    GT
+        The GT object is returned. This is the same object that the method is called on so that we
+        can facilitate method chaining.
+
+    Examples
+    --------
+    The use of `with_id` is straightforward—simply pass a string to `id=` to set the table ID:
+    ```{python}
+    from great_tables import GT, exibble
+
+    GT(exibble).with_id("your-table-id")
+    ```
     """
     return self._replace(_options=self._options._set_option_value("table_id", id))

great_tables/_spanners.py

@@ -107,16 +107,60 @@ def tab_spanner(
     )
     ```
 
-    We can also use Markdown formatting for the spanner label. In this example, we'll use
-    `gt.md("*Performance*")` to make the label italicized.
+    One cool feature of `tab_spanner()` is its support for multiple levels, allowing you to group
+    columns in various ways. For example, you can create three bottom spanners and a top spanner:
 
     ```{python}
-    from great_tables import GT, md
-    from great_tables.data import gtcars
+    (
+        GT(gtcars_mini)
+        .tab_spanner(
+            label="hp",
+            columns=["hp", "hp_rpm"],
+        )
+        .tab_spanner(
+            label="trq",
+            columns=["trq", "trq_rpm"],
+        )
+        .tab_spanner(
+            label="mpg",
+            columns=["mpg_c", "mpg_h"],
+        )
+        .tab_spanner(
+            label="performance",
+            columns=["hp", "hp_rpm", "trq", "trq_rpm", "mpg_c", "mpg_h"],
+        )
+    )
+    ```
 
-    colnames = ["model", "hp", "hp_rpm", "trq", "trq_rpm", "mpg_c", "mpg_h"]
-    gtcars_mini = gtcars[colnames].head(10)
+    Did you notice that the spanners stacked automatically? What if you want granular control to
+    specify a spanner in a specific hierarchy? **Great Tables** has you covered. By using the `level=`
+    parameter, you can easily adjust the hierarchy of spanners. For example, by specifying `level=0`
+    for the last call of `tab_spanner()`, you can place that spanner at the bottom level (level `0`)
+    instead of the top level (level `2`).
 
+    ```{python}
+    (
+        GT(gtcars_mini)
+        .tab_spanner(
+            label="hp",
+            columns=["hp", "hp_rpm"],
+        )
+        .tab_spanner(
+            label="performance",
+            columns=["hp", "hp_rpm", "trq", "trq_rpm"],
+        )
+        .tab_spanner(
+            label="trq",
+            columns=["trq", "trq_rpm"],
+            level=0,
+        )
+    )
+    ```
+
+    We can also use Markdown formatting for the spanner label. In this example, we'll use
+    `gt.md("*Performance*")` to make the label italicized.
+
+    ```{python}
     (
         GT(gtcars_mini)
         .tab_spanner(