[Docs] Restructure of Vizro-AI dashboard docs

vizro-ai/docs/index.md

@@ -8,25 +8,6 @@ Even if you are an experienced data practitioner, Vizro-AI optimizes how you cre
 
 <img src=".//assets/readme/readme_animation.gif" alt="Gif to demonstrate vizro-ai">
 
-Below is a table of the Vizro components currently supported by Vizro-AI. This list is not exhaustive, and we are actively working on adding more features to Vizro-AI.
-
-| Feature type         | Feature                                                                                                                | Availability |
-|----------------------|------------------------------------------------------------------------------------------------------------------------|--------------|
-| **Components**       | [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph/)                                               | ✔            |
-|                      | [AG Grid](https://vizro.readthedocs.io/en/stable/pages/user-guides/table/#ag-grid)                                     | ✔            |
-|                      | [Card](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/)                                          | ✔            |
-|                      | [Button](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/)                                        | ✖            |
-|                      | [Tabs](https://vizro.readthedocs.io/en/stable/pages/user-guides/tabs/)                                                 | ✖            |
-|                      | [Containers](https://vizro.readthedocs.io/en/stable/pages/user-guides/container/)                                      | ✖            |
-| **Controls**         | [Filter](https://vizro.readthedocs.io/en/stable/pages/user-guides/filters/)                                            | ✔            |
-|                      | [Parameter](https://vizro.readthedocs.io/en/stable/pages/user-guides/parameters/)                                      | ✖            |
-| **Navigation**       | [Default navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#use-the-default-navigation)  | ✔            |
-|                      | [Custom navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#customize-the-navigation-bar) | ✖            |
-| **Layout**           | [Layout](https://vizro.readthedocs.io/en/stable/pages/user-guides/layouts/)                                            | ✔            |
-| **Dashboard header** | [Dashboard title](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/)                                 | ✔            |
-|                      | [Logo](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/)                                            | ✖            |
-
-If a feature you need for your dashboard isn't currently supported by Vizro-AI you can [retrieve the dashboard code](https://vizro.readthedocs.io/projects/vizro-ai/en/vizro-ai-0.2.3/pages/user-guides/retrieve-dashboard-code/) and add the missing components before running the dashboard.
 
 <div class="grid cards" markdown>
 

vizro-ai/docs/pages/user-guides/create-advanced-charts.md

@@ -1,9 +1,9 @@
 # Advanced charts
 This page explains how to use Vizro-AI to create charts with advanced visualizations and enhanced formatting.
 
-## Animated bar chart
+## Animated map chart
 
-We'll create an animated bar chart illustrating the GDP per capita of each continent over time. Run the code below and look at the result.
+We'll create an animated map chart illustrating the GDP per capita of each continent over time. Run the code below and look at the result.
 
 !!! example "Vizro-AI animated chart"
 
@@ -76,3 +76,65 @@ Congratulations! You've now gained insights into harnessing the power of a LLM a
 
 
 Advanced charts are well-suited for [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard applications. You can create a chart using `vizro-ai` to plug into your `vizro` dashboard in seconds!
+
+
+## Polar bar chart
+
+A polar bar chart is a circular graph where each axis represents a different variable, typically used for displaying cyclical or directional data.
+It's suitable for comparing multiple variables across different categories or directions. Let's make one using Vizro-AI.
+
+
+!!! example "Polar Bar Chart"
+
+    === "Resulting chart"
+        [![VizroAIChart1]][VizroAIChart1]
+
+    === "Code for the cell"
+        ```py
+        import vizro_ai
+        from vizro_ai import VizroAI
+        import plotly.express as px
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        df = px.data.wind()
+
+        vizro_ai = VizroAI(model="gpt-4o")
+        fig = vizro_ai.plot(df,
+                      """Describe wind frequency and direction using bar_polar chart.
+                         Increase the width and height of the figure.
+                         Improve layout by placing title to the left. Show legend""")
+        fig.show()
+        ```
+
+    [VizroAIChart1]: ../../assets/user_guides/polar_bar_chart.png
+
+
+
+## 3D surface plot
+
+Let's explore how to generate a 3-dimensional surface plot with VizroAI.
+
+!!! example "Surface plot"
+
+    === "Resulting chart"
+        [![VizroAIChart3]][VizroAIChart3]
+
+    === "Code for the cell"
+        ```py
+        import vizro_ai
+        from vizro_ai import VizroAI
+        import plotly.express as px
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        df = px.data.gapminder()
+
+        vizro_ai = VizroAI(model="gpt-4o")
+        fig = vizro_ai.plot(df, "create a surface plot")
+        fig.show()
+        ```
+
+    [VizroAIChart3]: ../../assets/user_guides/surface_plot.gif

vizro-ai/docs/pages/user-guides/create-complex-dashboard.md

@@ -105,9 +105,75 @@ The call to `dashboard()` triggers the dashboard building process. Once Vizro-AI
 
 !!! example "Generated dashboard"
 
-    === "Code"
+    === "Code for the cell"
+
         ```py
+        import vizro_ai
+        from vizro_ai import VizroAI
+        import plotly.express as px
+
+        from dotenv import load_dotenv
+        load_dotenv()
+
+        df1 = px.data.election()
+        df2 = px.data.stocks(datetimes=True)
+
+        user_question = """
+        Create a 2-page dashabord.
+
+        <Page 1>
+        Visualize the election result.
+
+        NOTE:
+        1. use consistent and default color scheme.
+           1. make axis label and chart title simple and readable.
+
+        I need 3 pie charts, 3 bar charts, 1 table, and 1 radio button as filter.
+
+        pie chart 1: shows number of votes Coderre received, compared to total votes.
+        pie chart 2: shows number of votes Bergeron received, compared to total votes.
+        pie chart 3: shows number of votes Joly received, compared to total votes.
+
+        bar chart 1: shows number of districts Coderre winned. put `result` on y-axis, put "count of districts" on x-axis.
+        bar chart 2: shows number of districts Bergeron winned. put `result` on y-axis, put "count of districts" on x-axis.
+        bar chart 3: shows number of districts Joly winned. put `result` on y-axis, put "count of districts" on x-axis.
+
+        use table to show the election data.
+
+        Layout of page 1:
+        Imaging the whole page is divided by a (3 by 3) grid, with 3 rows and 3 columns.
+        Row 1 - pie chart 1 takes column 1; pie chart 2 takes column 2; pie chart 3 takes column 3.
+        Row 2 - bar chart 1 takes column 1; bar chart 2 takes column 2; bar chart 3 takes column 3.
+        Row 3 - the table span all three columns.
+
+        Add a filter to filter all pie charts by district, using radio button as selelctor.
+
+
+        <Page 2>
+        Visualize the tech company stock data.
+        I need 1 line chart, 6 cards.
+
+        line chart: shows the stock price history of all comanies. put data on x-axis, company names as facet_row. make the y-axis label simple and readable.
+
+        For cards, render the exact text as requested.
+        Card 1 has text `> Dow Jones \n\n ## **39,737.26**\n`
+        Card 2 has text `> S&P 500 \n\n ## **4,509.61**\n`
+        Card 3 has text `> NASDAQ Composite \n\n ## **14,141.48**\n`
+        Card 4 has text `> FTSE 100 \n\n ## **7,592.66**\n`
+        Card 5 has text `> DAX \n\n ## **15,948.85**\n`
+        Card 6 has text `> Nikkei 225 \n\n ## **32,210.78**\n`
+
+        Page Layout:
+        In a grid of 7 rows and 6 columns:
+        column 1 to column 5 - the line chart spans 5 columns (all 7 rows) from the left.
+        column 6 - card 1 takes row 1; card 2 takes row 2; card 3 takes row 3; ... card 6 takes row 6; row 7 is empty.
+        """
+
+        vizro_ai = VizroAI(model="gpt-4o")
+        dashboard = vizro_ai.dashboard([df1, df2], user_question)
+
         Vizro().build(dashboard).run()
+
         ```
 
     === "Page1"

vizro-ai/docs/pages/user-guides/run-vizro-ai-dashboard.md

@@ -0,0 +1,175 @@
+# How to run Vizro-AI dashboard
+
+This guide offers insights into different ways of running `VizroAI.dashboard` to generate Vizro dashboard.
+
+??? note "Note: API key"
+
+    Make sure you have followed the [LLM setup guide](../user-guides/install.md#set-up-access-to-a-large-language-model) and thatyour api key is set up in a `.env` file in the same folder as your Notebook file (`.ipynb`).
+
+## Run Vizro-AI dashboard
+
+### 1. Prepare the data and user prompt
+```py
+import vizro.plotly.express as px
+
+df = px.data.tips()
+
+user_question = """
+Create a one-page dashboard layout with the following components:
+
+1. Card:
+   - Position: Left of the page
+   - Size: Takes up 1/4 of the total page width
+   - Content: Display the text "This is Tips dataset"
+
+2. Table:
+   - Position: Right of the card
+   - Size: Takes up the remaining 3/4 of the page width
+   - Content: Display the Tips dataset
+"""
+```
+
+### 2. Generate and launch the dashboard
+```py
+from vizro_ai import VizroAI
+
+vizro_ai = VizroAI(model="gpt-4o-mini")
+dashboard = vizro_ai.dashboard([df], user_question)
+```
+This triggers the dashboard building process. Once Vizro-AI finishes the dashboard generation process, you can now launch the dashboard.
+
+!!! example "Generated dashboard"
+
+    === "Code"
+        ```py
+        import vizro.plotly.express as px
+        from vizro_ai import VizroAI
+        from vizro import Vizro
+
+        df = px.data.tips()
+        user_question = """
+        Create a one-page dashboard layout with the following components:
+
+        1. Card:
+           - Position: Left of the page
+           - Size: Takes up 1/4 of the total page width
+           - Content: Display the text "This is Tips dataset"
+
+        1. Table:
+           - Position: Right of the card
+           - Size: Takes up the remaining 3/4 of the page width
+           - Content: Display the Tips dataset
+        """
+        vizro_ai = VizroAI(model="gpt-4o-mini")
+        dashboard = vizro_ai.dashboard([df], user_question)
+        Vizro().build(dashboard).run()
+        ```
+
+    === "Result"
+        [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
+
+
+    [VizroAIDashboardPage1]: ../../assets/user_guides/dashboard/dashboard2_page1.png
+
+## Retrieve the Python code of the dashboard
+
+To illustrate the process, lets re-use the example provided above.
+
+Like the `VizroAI.plot` method, in order to produce more comprehensive output we need to set `return_elements=True`. `return_elements` is a boolean (by default `False`) which determines the return type of `VizroAI.dashboard`.
+
+- If set to `False` it produces a `Vizro` dashboard object.
+- If set to `True`, it returns a class (a Pydantic model) containing both the dashboard object and the code string used to generate it.
+
+!!! example "View dashboard code"
+
+    === "Code"
+        ```py
+        import vizro.plotly.express as px
+        from vizro_ai import VizroAI
+        from vizro import Vizro
+
+        df = px.data.tips()
+        user_question = """
+        Create a one-page dashboard layout with the following components:
+
+        1. Card:
+           - Position: Left of the page
+           - Size: Takes up 1/4 of the total page width
+           - Content: Display the text "This is Tips dataset"
+
+        1. Table:
+           - Position: Right of the card
+           - Size: Takes up the remaining 3/4 of the page width
+           - Content: Display the Tips dataset
+        """
+        vizro_ai = VizroAI(model="gpt-4o-mini")
+        result = vizro_ai.dashboard([df], user_question, return_elements=True)
+
+        print(result.code)
+        ```
+    === "Result"
+        ```py
+        ######## Module Imports ##########
+        from vizro import Vizro
+        from vizro.managers import data_manager
+        from vizro.models.types import capture
+        import vizro.models as vm
+        from vizro.tables import dash_ag_grid
+
+        ########## Data Imports ##########
+        #####!!! UNCOMMENT BELOW !!!######
+        # data_manager["restaurant_bills"] = ===> Fill in here <===
+
+        ###### Callable definitions ######
+
+
+        ########## Object code ###########
+        dashboard = vm.Dashboard(
+           pages=[
+               vm.Page(
+                   id="Tips Data Visualization",
+                   components=[
+                       vm.Card(
+                           id="tips_card_tips_data_visualization",
+                           type="card",
+                           text="This is Tips dataset",
+                           href="",
+                       ),
+                       vm.AgGrid(
+                           id="tips_table_tips_data_visualization",
+                           figure=dash_ag_grid(data_frame="restaurant_bills"),
+                       ),
+                   ],
+                   title="Tips Data Visualization",
+                   layout=vm.Layout(grid=[[0, 1, 1, 1]]),
+                   controls=[],
+               )
+           ],
+           title="Tips Dataset Overview",
+        )
+        ```
+
+## Available Vizro components
+
+Below is a table of the Vizro components currently supported by Vizro-AI. This list is not exhaustive, and we are actively working on adding more features to Vizro-AI.
+
+| Feature type         | Feature                                                                                                                                  | Availability |
+|----------------------|------------------------------------------------------------------------------------------------------------------------------------------|-------------|
+| **Components**       | [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph/)                                                                 | ✔           |
+|                      | [AG Grid](https://vizro.readthedocs.io/en/stable/pages/user-guides/table/#ag-grid)                                                       | ✔           |
+|                      | [Card](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/)                                                            | ✔           |
+|                      | [Button](https://vizro.readthedocs.io/en/stable/pages/user-guides/card-button/)                                                          | ✖           |
+|                      | [Tabs](https://vizro.readthedocs.io/en/stable/pages/user-guides/tabs/)                                                                   | ✖           |
+|                      | [Containers](https://vizro.readthedocs.io/en/stable/pages/user-guides/container/)                                                        | ✖           |
+| **Controls**         | [Filter](https://vizro.readthedocs.io/en/stable/pages/user-guides/filters/)                                                              | ✔           |
+|                      | [Parameter](https://vizro.readthedocs.io/en/stable/pages/user-guides/parameters/)                                                        | ✖           |
+| **Navigation**       | [Default navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#use-the-default-navigation)                    | ✔           |
+|                      | [Custom navigation](https://vizro.readthedocs.io/en/stable/pages/user-guides/navigation/#customize-the-navigation-bar)                   | ✖           |
+| **Layout**           | [Layout](https://vizro.readthedocs.io/en/stable/pages/user-guides/layouts/)                                                              | ✔           |
+| **Dashboard header** | [Dashboard title](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/)                                                   | ✔           |
+|                      | [Logo](https://vizro.readthedocs.io/en/stable/pages/user-guides/dashboard/)                                                              | ✖           |
+| **Actions**          | [Pre-defined actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#pre-defined-actions/)                            | ✖           |
+|                      | [Filter interaction between charts](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#filter-data-by-clicking-on-chart/) | ✖           |
+|                      | [Custom actions](https://vizro.readthedocs.io/en/stable/pages/user-guides/actions/#custom-actions/)                                      | ✖           |
+
+If a feature you need for your dashboard isn't currently supported by Vizro-AI you can retrieve the dashboard code and add the missing components before running the dashboard.

vizro-ai/mkdocs.yml

@@ -16,8 +16,8 @@ nav:
           - Advanced charts: pages/user-guides/create-advanced-charts.md
           - Add Vizro-AI charts to a Vizro dashboard: pages/user-guides/add-generated-chart-usecase.md
       - DASHBOARDS:
-          - Generate a complex dashboard: pages/user-guides/create-complex-dashboard.md
-          - Retrieve code for a generated dashboard: pages/user-guides/retrieve-dashboard-code.md
+          - Run vizro_ai.dashboard: pages/user-guides/run-vizro-ai-dashboard.md
+          - Advanced dashboard: pages/user-guides/create-complex-dashboard.md
           - Use Vizro-AI methods as Langchain tools: pages/user-guides/vizro-ai-langchain-guide.md
   - API Reference:
       - VizroAI: pages/API-reference/vizro-ai.md
@@ -26,8 +26,8 @@ nav:
       - Disclaimer: pages/explanation/disclaimer.md
       - Safeguard code execution: pages/explanation/safeguard.md
       - Safety in Vizro-AI: pages/explanation/safety-in-vizro-ai.md
-  - Examples:
-      - Chart examples: pages/user-guides/chart-examples.md
+  - Try out!:
+      - Try out!: https://vizro.mckinsey.com
   #- Contribute:
   #      - Contributing: pages/contribute/contributing.md
   - Vizro:

vizro-core/mkdocs.yml

@@ -55,7 +55,7 @@ nav:
       - Contribute to Vizro: pages/explanation/contributing.md
       - Documentation style: pages/explanation/documentation-style-guide.md
       - Authors: pages/explanation/authors.md
-  - Examples:
+  - Try out!:
       - Vizro gallery: https://vizro.mckinsey.com/
   - Vizro-AI:
       - Vizro-AI: https://vizro.readthedocs.io/projects/vizro-ai/