[Docs] Add documentation and examples for Figure (#524)

Co-authored-by: Jo Stichbury <[email protected]>
Co-authored-by: Antony Milne <[email protected]>

vizro-core/changelog.d/20240607_125345_huong_li_nguyen_create_kpi_cards.md

@@ -6,8 +6,8 @@ Uncomment the section that is right (remove the HTML comment wrapper).
 
 ### Highlights ✨
 
-- Introduce `Figure` as a new `Page` component, enabling all dash components to be reactive in
-  `Vizro`. See the [user guide on figure](XXXX) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493))
+- Introduce `Figure` as a new `Page` component, enabling all Dash components to be reactive in
+  `Vizro`. See the [user guide on figure](https://vizro.readthedocs.io/en/stable/pages/user-guides/figure/) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493), [#524](https://github.com/mckinsey/vizro/pull/524))
 - Introduce styled KPI cards to be used inside `Figure`. See the [user guide on KPI cards](XXXX) for more information. ([#493](https://github.com/mckinsey/vizro/pull/493))
 
 <!--

vizro-core/changelog.d/20240618_130057_huong_li_nguyen_add_figure.md

@@ -0,0 +1,48 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Highlights ✨
+
+- A bullet item for the Highlights ✨ category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Removed
+
+- A bullet item for the Removed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category with a link to the relevant PR at the end of your entry, e.g. Enable feature XXX ([#1](https://github.com/mckinsey/vizro/pull/1))
+
+-->

vizro-core/docs/pages/API-reference/actions.md → vizro-core/docs/pages/API-reference/action-callables.md

@@ -1,4 +1,4 @@
-# Actions
+# Action functions
 <!-- vale off -->
 
 API reference for all pre-defined action functions.

vizro-core/docs/pages/API-reference/figure-callables.md

@@ -0,0 +1,10 @@
+<!-- vale off -->
+# Figure functions
+API reference for all pre-defined [`CapturedCallable`][vizro.models.types.CapturedCallable] figure functions to be used in the
+[`Figure`][vizro.models.Figure]. The [how-to guide on figures](../user-guides/figure.md) contains more information.
+
+::: vizro.figures
+    options:
+      show_source: true
+
+<!-- vale on -->

vizro-core/docs/pages/API-reference/table-callables.md

@@ -0,0 +1,11 @@
+<!-- vale off -->
+# Table functions
+
+API reference for all pre-defined [`CapturedCallable`][vizro.models.types.CapturedCallable] table functions to be used in the
+[`AgGrid`][vizro.models.AgGrid] and [`Table`][vizro.models.Table] models. The how-to guide on [tables](../user-guides/table.md) contains more information.
+
+::: vizro.tables
+    options:
+      show_source: true
+
+<!-- vale on -->

vizro-core/docs/pages/user-guides/components.md

@@ -6,39 +6,40 @@ listed below to fill your dashboard with visuals.
 
 <div class="grid cards" markdown>
 
-- :octicons-graph-16:{ .lg .middle } __Graph__
+- :octicons-graph-16:{ .lg .middle } __Graphs__
 
     ---
 
     Use graphs to visualize your data with any Plotly chart.
 
     [:octicons-arrow-right-24: View user guide](graph.md)
 
-- :material-table-large:{ .lg .middle } __Table__
+- :material-table-large:{ .lg .middle } __Tables__
 
     ---
 
     Use tables to visualize your tabular data.
 
     [:octicons-arrow-right-24: View user guide](table.md)
 
-- :material-cards-outline:{ .lg .middle } __Card & button__
+- :material-graph:{ .lg .middle } __Figures__
 
     ---
 
-    Use cards and buttons to visualize text, navigate to different URLs or attach any [action](actions.md).
+    Use figures to make any [Dash component](https://dash.plotly.com/#open-source-component-libraries) reactive.
 
-    [:octicons-arrow-right-24: View user guide](card-button.md)
+    [:octicons-arrow-right-24: View user guide](figure.md)
 
-- :material-graph:{ .lg .middle } __Figure__
+- :material-cards-outline:{ .lg .middle } __Cards & buttons__
 
     ---
 
-    Use figure to visualize your make any dash component reactive.
+    Use cards and buttons to visualize text, navigate to different URLs or attach any [action](actions.md).
+
+    [:octicons-arrow-right-24: View user guide](card-button.md)
 
-    [:octicons-arrow-right-24: View user guide](figure.md)
 
-- :octicons-table-16:{ .lg .middle } __Container__
+- :octicons-table-16:{ .lg .middle } __Containers__
 
     ---
 

vizro-core/docs/pages/user-guides/custom-charts.md

@@ -3,26 +3,27 @@
 This guide shows you how to create custom charts and how to add them to your dashboard.
 The [`Graph`][vizro.models.Graph] model accepts the `figure` argument, where you can enter _any_ [`plotly.express`](https://plotly.com/python/plotly-express/) chart as explained in the [user guide on graphs](graph.md).
 
-## Overview of custom charts
+## When to use a custom chart
+In general, you should use the custom chart decorator `@capture("graph")` if your plotly chart needs any post-update calls or customization. For example:
 
-In general, the usage of the custom chart decorator `@capture("graph")` is required if your plotly chart requires any post-update calls or customization.
+- You want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
+- You want to use a custom-created [`plotly.graph_objects.Figure()`](https://plotly.com/python/graph-objects/) object (in short, `go.Figure()`) and add traces yourself via [`add_trace`](https://plotly.com/python/creating-and-updating-figures/#adding-traces)
 
-### When to use a custom chart
+## Steps to create a custom chart
 
-- If you want to use any of the post figure update calls by `plotly` such as `update_layout`, `update_xaxes`, `update_traces` (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
-- If you want to use a custom-created [`plotly.graph_objects.Figure()`](https://plotly.com/python/graph-objects/) object (in short, `go.Figure()`) and add traces yourself via [`add_trace`](https://plotly.com/python/creating-and-updating-figures/#adding-traces)
+1. Define a function that returns a `go.Figure()`.
+2. Decorate it with `@capture("graph")`.
+3. The function must accept a `data_frame` argument (of type `pandas.DataFrame`).
+4. The visualization should be derived from and require only one `pandas.DataFrame`. Dataframes from other arguments
+will not react to dashboard controls such as [`Filter`](filters.md).
+5. Pass your function to the `figure` argument of the [`Graph`][vizro.models.Graph] model.
 
-### Requirements of a custom chart function
-
-- a `go.Figure()` object is returned by the function
-- the function must be decorated with the `@capture("graph")` decorator
-- the function accepts a `data_frame` argument (of type `pandas.DataFrame`)
-- the visualization is derived from and requires only one `pandas.DataFrame` (for example, any further dataframes added through other arguments will not react to dashboard components such as `Filter`)
-
-The below minimal example can be used as a base to build more sophisticated charts.
+The minimal example below can be used as a base to build more sophisticated charts.
 
 ```py title="Minimal example of a custom chart"
 from vizro.models.types import capture
+import pandas as pd
+import plotly.graph_objects as go
 
 @capture("graph")
 def minimal_example(data_frame:pd.DataFrame=None):

vizro-core/docs/pages/user-guides/custom-components.md

@@ -11,7 +11,7 @@ In general, you can create a custom component based on any dash-compatible compo
 
 
 All our components are based on `Dash`, and they are shipped with a set of sensible defaults that can be modified. If you would like to overwrite one of those defaults,
-or if you would like to use extra `args` or `kwargs` of those components, then this is the correct way to include those. You can use any existing attribute of any underlying Dash component with this method.
+or if you would like to use extra `args` or `kwargs` of those components, then this is the correct way to include those. You can use any existing attribute of any underlying [Dash component](https://dash.plotly.com/#open-source-component-libraries) with this method.
 
 !!!note