From 87bce4f9503a956286019f096dc11d63a797a117 Mon Sep 17 00:00:00 2001
From: huong-li-nguyen <huong_li_nguyen@mckinsey.com>
Date: Thu, 18 Jul 2024 16:56:26 +0200
Subject: [PATCH] Add example usage inside docstrings

---
 vizro-core/src/vizro/figures/kpi_cards.py    | 12 ++++++++++++
 vizro-core/src/vizro/tables/_dash_ag_grid.py | 10 +++++++++-
 vizro-core/src/vizro/tables/_dash_table.py   | 10 +++++++++-
 3 files changed, 30 insertions(+), 2 deletions(-)

diff --git a/vizro-core/src/vizro/figures/kpi_cards.py b/vizro-core/src/vizro/figures/kpi_cards.py
index ed60a5305..9d199b2a0 100644
--- a/vizro-core/src/vizro/figures/kpi_cards.py
+++ b/vizro-core/src/vizro/figures/kpi_cards.py
@@ -56,6 +56,12 @@ def kpi_card(  # noqa: PLR0913
     Returns:
          A Dash Bootstrap Components card (`dbc.Card`) containing the formatted KPI value.
 
+    Examples:
+        Wrap inside `vm.Figure` to use as a component inside `vm.Page` or `vm.Container`.
+        >>> import vizro.models as vm
+        >>> from vizro.figures import kpi_card
+        >>> vm.Page(title="Page", components=[vm.Figure(figure=kpi_card(...))])
+
     """
     title = title or f"{agg_func} {value_column}".title()
     value = data_frame[value_column].agg(agg_func)
@@ -119,6 +125,12 @@ def kpi_card_reference(  # noqa: PLR0913
     Returns:
         A Dash Bootstrap Components card (`dbc.Card`) containing the formatted KPI value and reference.
 
+    Examples:
+        Wrap inside `vm.Figure` to use as a component inside `vm.Page` or `vm.Container`.
+        >>> import vizro.models as vm
+        >>> from vizro.figures import kpi_card_reference
+        >>> vm.Page(title="Page", components=[vm.Figure(figure=kpi_card_reference(...))])
+
     """
     title = title or f"{agg_func} {value_column}".title()
     value, reference = data_frame[[value_column, reference_column]].agg(agg_func)
diff --git a/vizro-core/src/vizro/tables/_dash_ag_grid.py b/vizro-core/src/vizro/tables/_dash_ag_grid.py
index cee45f99c..dec4efeca 100644
--- a/vizro-core/src/vizro/tables/_dash_ag_grid.py
+++ b/vizro-core/src/vizro/tables/_dash_ag_grid.py
@@ -48,7 +48,15 @@
 
 @capture("ag_grid")
 def dash_ag_grid(data_frame: pd.DataFrame, **kwargs) -> dag.AgGrid:
-    """Implementation of `dash_ag_grid.AgGrid` with sensible defaults to be used in [`AgGrid`][vizro.models.AgGrid]."""
+    """Implementation of `dash_ag_grid.AgGrid` with sensible defaults to be used in [`AgGrid`][vizro.models.AgGrid].
+
+    Examples
+        Wrap inside `vm.AgGrid` to use as a component inside `vm.Page` or `vm.Container`.
+        >>> import vizro.models as vm
+        >>> from vizro.tables import dash_ag_grid
+        >>> vm.Page(title="Page", components=[vm.AgGrid(figure=dash_ag_grid(...))])
+
+    """
     defaults = {
         "className": "ag-theme-quartz-dark ag-theme-vizro",
         "columnDefs": [{"field": col} for col in data_frame.columns],
diff --git a/vizro-core/src/vizro/tables/_dash_table.py b/vizro-core/src/vizro/tables/_dash_table.py
index da6087b78..d55d818c3 100644
--- a/vizro-core/src/vizro/tables/_dash_table.py
+++ b/vizro-core/src/vizro/tables/_dash_table.py
@@ -9,7 +9,15 @@
 
 @capture("table")
 def dash_data_table(data_frame: pd.DataFrame, **kwargs) -> dash_table.DataTable:
-    """Standard `dash_table.DataTable` with sensible defaults to be used in [`Table`][vizro.models.Table]."""
+    """Standard `dash_table.DataTable` with sensible defaults to be used in [`Table`][vizro.models.Table].
+
+    Examples
+        Wrap inside `vm.Table` to use as a component inside `vm.Page` or `vm.Container`.
+        >>> import vizro.models as vm
+        >>> from vizro.table import dash_data_table
+        >>> vm.Page(title="Page", components=[vm.Table(figure=dash_data_table(...))])
+
+    """
     defaults = {
         "columns": [{"name": col, "id": col} for col in data_frame.columns],
         "style_as_list_view": True,