[Docs] Revise Vizro-AI docs for dashboard generation pages

vizro-ai/changelog.d/20240731_160839_jo_stichbury_revise_vizroai_docset.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-ai/docs/index.md

@@ -1,10 +1,10 @@
 # Vizro-AI
 
-Vizro-AI extends [Vizro](https://vizro.readthedocs.io) to enable a user to use English or other languages to effortlessly create interactive charts with [Plotly](https://plotly.com/python/).
+Vizro-AI uses generative AI to extend [Vizro](https://vizro.readthedocs.io) so you can use instructions in English, or other languages, to effortlessly create interactive charts and dashboards.
 
-If you're new to coding, Vizro-AI simplifies the process of creating charts that offer detailed insights about your data. Even if you're an experienced data practitioner, Vizro-AI optimizes how you create visually appealing charts.
+By using Vizro's themes, you can incorporate design best practices by default. If you're new to coding, Vizro-AI simplifies both the creation of charts with [Plotly](https://plotly.com/python/) and their layout upon an interactive and easily-distributed dashboard.
 
-Vizro-AI uses a large language model and Plotly to generate code for an interactive chart that you can add into a [Vizro dashboard application](https://vizro.readthedocs.io). By using Vizro's themes, you can incorporate design best practices by default.
+Even if you are an experienced data practitioner, Vizro-AI optimizes how you create visually appealing layouts to present detailed insights about your data.
 
 <img src=".//assets/readme/readme_animation.gif" alt="Gif to demonstrate vizro-ai">
 
@@ -15,18 +15,18 @@ Vizro-AI uses a large language model and Plotly to generate code for an interact
     ---
 
     [:octicons-arrow-right-24: Install Vizro-AI](pages/user-guides/install.md) </br>
-    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/quickstart.md)
-
+    [:octicons-arrow-right-24: Quickstart chart generation](pages/tutorials/quickstart.md) </br>
+    [:octicons-arrow-right-24: Quickstart dashboard generation](pages/tutorials/quickstart-dashboard.md) </br>
 
 - :fontawesome-solid-keyboard:{ .lg .middle } __Get hands-on__
 
     ---
 
-    [:octicons-arrow-right-24: Ways to run Vizro-AI](pages/user-guides/run-vizro-ai.md)</br>
-    [:octicons-arrow-right-24: Customize models](pages/user-guides/customize-vizro-ai.md)</br>
+    [:octicons-arrow-right-24: How to run Vizro-AI](pages/user-guides/run-vizro-ai.md)</br>
+    [:octicons-arrow-right-24: Model usage](pages/user-guides/customize-vizro-ai.md)</br>
     [:octicons-arrow-right-24: Create advanced charts](pages/user-guides/create-advanced-charts.md)</br>
-    [:octicons-arrow-right-24: Use different languages](pages/user-guides/use-different-languages.md)</br>
-    [:octicons-arrow-right-24: Add charts to a dashboard](pages/user-guides/add-generated-chart-usecase.md)
+    [:octicons-arrow-right-24: Add charts to a dashboard](pages/user-guides/add-generated-chart-usecase.md)</br>
+    [:octicons-arrow-right-24: Generate a complex dashboard](pages/user-guides/create-complex-dashboard.md)
 
 - :material-format-font:{ .lg .middle } __Find out more__
 

vizro-ai/docs/pages/tutorials/quickstart-dashboard.md

@@ -0,0 +1,93 @@
+# Dashboard generation
+
+In the previous tutorial, we explained how to use Vizro-AI to generate individual charts from text. Vizro-AI also supports text-to-dashboard functionality, enabling you to generate a complete [Vizro](https://vizro.readthedocs.io/en/stable/) dashboard containing multiple charts and pages.
+
+You may also want to review the [Vizro dashboard tutorial](https://vizro.readthedocs.io/en/stable/pages/tutorials/first-dashboard/), which creates a dashboard from scratch rather than by generation with Vizro-AI.
+
+## 1. Install Vizro-AI and its dependencies
+
+If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
+
+
+## 2. Open a Notebook
+A good way to initially explore Vizro-AI is from inside a Jupyter Notebook.
+
+??? "If you haven't used Jupyter before..."
+
+    You may need to install the Jupyter package if you . From the terminal window:
+
+    ```bash
+    pip install jupyter
+    ```
+
+Start a new Notebook as follows:
+
+```bash
+jupyter notebook
+```
+
+The command opens Jupyter in a browser tab. Use the UI to navigate to a preferred folder in which to create this new dashboard.
+
+Create a new `Python 3 (ipykernel)` Notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it.
+
+```py
+import vizro_ai
+
+print(vizro_ai.__version__)
+```
+
+You should see a return output of the form `x.y.z`.
+
+
+## 3. Prepare the data
+Next, prepare the data to pass to Vizro-AI. In this example, we use the [gapminder data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.gapminder).
+
+```py
+import vizro.plotly.express as px
+
+df = px.data.gapminder(datetimes=True, pretty_names=True)
+```
+
+## 4. Prepare the user prompt
+
+Put together a string of text which is the prompt to request Vizro-AI to generate the dashboard.
+
+Vizro-AI can generate a multi-page dashboard that includes the following features:
+
+- Vizro components including `Graph`, `AgGrid` (basic), and `Card`
+- Vizro filters including `Dropdown`, `Checklist`, `RadioItems`, `RangeSlider`, `Slider`, and `DatePicker`
+- Vizro `Layout`
+- Multi-dataframe and multi-page support
+
+```text
+user_question = """
+Create a page showing 1 card, 1 chart, and 1 filter.
+The first card says 'The Gapminder dataset is a detailed collection of global socioeconomic indicators over several decades. It includes data on GDP per capita, life expectancy, and population for numerous countries and regions. This dataset allows users to analyze development trends, health outcomes, economic growth, and demographic changes globally.'
+The chart is a box plot showing life expectancy distribution. Put Life expectancy on the y axis, continent on the x axis, and color by continent.
+The card takes 1 grid of the page space on the left and the box plot takes 3 grid space on the right.
+
+Add a filter to filter the box plot by year.
+"""
+```
+
+## 5. Call Vizro-AI
+
+Next, submit the data and prompt string:
+
+```py
+dashboard = vizro_ai.dashboard([df], user_question)
+```
+
+The call to `dashboard()` triggers the dashboard building process. Once Vizro-AI finishes the dashboard generation process, you can launch the dashboard with `build()`.
+
+!!! example "Generated dashboard"
+
+    === "Code"
+        ```py
+        Vizro().build(dashboard).run()
+        ```
+
+    === "Result"
+        [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
+
+    [VizroAIDashboardPage1]: ../../assets/tutorials/dashboard/dashboard0_page1.png

vizro-ai/docs/pages/tutorials/quickstart.md

@@ -1,8 +1,8 @@
-# Get started with Vizro-AI
-This tutorial introduces you to Vizro-AI, which is an English-to-visualization package. In a series of steps, we will explain the basics and set you up with the knowledge to explore the package further.
+# Chart generation
+This tutorial introduces you to chart generation using Vizro-AI. It explains the basics of creating a plotly chart that can be added to a Vizro dashboard. When you have followed it, you are set up to explore the Vizro and Vizro-AI packages further.
 
 <!-- vale off -->
-### 1. Install Vizro and its dependencies
+### 1. Install Vizro-AI and its dependencies
 <!-- vale on -->
 
 If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
@@ -40,7 +40,7 @@ print(vizro_ai.__version__)
 You should see a return output of the form `x.y.z`.
 
 <!-- vale off -->
-### 3. Create your first chart using Vizro-AI
+### 3. Create your first plotly chart using Vizro-AI
 <!-- vale on -->
 
 Let's create a chart to illustrate the GDP of various continents while including a reference line for the average. We give Vizro-AI the English language instruction "*describe the composition of GDP in continent and color by continent, and add a horizontal line for avg GDP*".
@@ -142,6 +142,6 @@ Let's create another example to illustrate the code and insights returned when p
 <!-- vale on -->
 
 
-Now, you have created your first charts with Vizro-AI you are ready to explore further.
+Congratulations! You have created your first charts with Vizro-AI and you are ready to explore further.
 
-A good place to start would be to review the different how-to guides, such as [how to run Vizro-AI](../user-guides/run-vizro-ai.md), [how to create visualizations using different languages](../user-guides/use-different-languages.md), and [how to create advanced charts](../user-guides/create-advanced-charts.md).
+A good place to start would be to review the different how-to guides to learn [the different ways to run Vizro-AI](../user-guides/run-vizro-ai.md), [how to create advanced charts](../user-guides/create-advanced-charts.md) and [how to add your Vizro-AI charts to a Vizro dashboard](../user-guides/add-generated-chart-usecase.md). You may also want to review the tutorial on [how to generate a Vizro dashboard with Vizro-AI](quickstart-dashboard.md)

vizro-ai/docs/pages/user-guides/add-generated-chart-usecase.md

@@ -1,8 +1,8 @@
-# How to add Vizro-AI created charts into a Vizro dashboard
+# How to add Vizro-AI created charts to a Vizro dashboard
 
-This guide explains the different ways in which you can add a chart generated by Vizro-AI to your [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard.
+This guide explains the different ways in which you can add a chart generated by Vizro-AI to an existing [Vizro dashboard](https://github.com/mckinsey/vizro/tree/main/vizro-core).
 
-###  Use Vizro-AI's generated code
+##  Use Vizro-AI's generated code
 
 1. Create a chart with Vizro-AI that you would like to visualize in a dashboard.
 
@@ -106,7 +106,7 @@ This object must then be passed to the `figure` argument of the Vizro [Graph](ht
     [VizroDashboard]: ../../assets/user_guides/chart_into_dashboard_large.gif
 
 
-### Use Vizro-AI dynamically to return a `fig` object
+## Use Vizro-AI dynamically to return a `fig` object
 
 We can also use Vizro-AI dynamically and assign the output of `plot()` directly to the fig variable, enabling its reuse in the `vm.Graph.figure` argument.
 This method offers streamlined efficiency, eliminating the need for code copying.
@@ -156,5 +156,3 @@ Executing the code below yields the identical dashboard as the example above.
         [![VizroDashboard2]][VizroDashboard2]
 
     [VizroDashboard2]: ../../assets/user_guides/chart_into_dashboard_2.gif
-
-With Vizro-AI you can create visually captivating charts and plug them into your [Vizro](https://github.com/mckinsey/vizro/tree/main/vizro-core) dashboard in seconds!

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

@@ -1,5 +1,7 @@
-# How to create advanced charts
-Now, let's explore more advanced visualizations and use Vizro-AI for enhanced formatting.
+# Advanced charts
+This page explains how to use Vizro-AI to create charts with advanced visualizations and enhanced formatting.
+
+## Animated bar 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.
 

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

@@ -0,0 +1,149 @@
+# Generate a complex dashboard
+
+This guide shows you how to instruct Vizro-AI generating a complex dashboard.
+
+Vizro-AI can in general follow user requirements well and generate high-quality dashboards, but the nature of LLMs means that generated dashboards are not always an exact match for user expectations. When the text length of user requirements increases, the LLMs could start to miss part of the user requirements or make mistakes. Apart from choosing more advanced models for harder tasks, improving the user prompt could help too.
+
+The following example shows how to use Vizro-AI to generate a complex Vizro dashboard.
+
+## 1. Install Vizro-AI and its dependencies
+
+If you haven't already installed Vizro-AI and set up the API key for OpenAI, follow the [installation guide](../user-guides/install.md).
+
+
+## 2. Open a Notebook
+A good way to initially explore Vizro-AI is from inside a Jupyter Notebook.
+
+??? "If you haven't used Jupyter before..."
+
+    You may need to install the Jupyter package if you . From the terminal window:
+
+    ```bash
+    pip install jupyter
+    ```
+
+Start a new Notebook as follows:
+
+```bash
+jupyter notebook
+```
+
+The command opens Jupyter in a browser tab. Use the UI to navigate to a preferred folder in which to create this new dashboard.
+
+Create a new `Python 3 (ipykernel)` Notebook from the "New" dropdown. Confirm your Vizro installation by typing the following into a cell in the Notebook and running it.
+
+```py
+import vizro_ai
+
+print(vizro_ai.__version__)
+```
+
+You should see a return output of the form `x.y.z`.
+
+
+## 3. Prepare the data
+Next, prepare the data to pass to Vizro-AI. In this example, we use the [election data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.election) and the [stocks data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.stocks).
+
+```py
+import vizro.plotly.express as px
+
+df1 = px.data.election()
+df2 = px.data.stocks(datetimes=True)
+```
+
+## 4. Prepare the user prompt
+
+Put together a string of text which is the prompt to request Vizro-AI to generate the dashboard.
+
+Vizro-AI can generate a multi-page dashboard that includes the following features:
+
+- Vizro components including `Graph`, `AgGrid` (basic), and `Card`
+- Vizro filters including `Dropdown`, `Checklist`, `RadioItems`, `RangeSlider`, `Slider`, and `DatePicker`
+- Vizro `Layout`
+- Multi-dataframe and multi-page support
+
+In this example, we are requesting a multi-dataframe and multi-page dashboard, which includes all types of components, one filter, and customized layout.
+
+```text
+user_question = """
+Create a 2-page dashabord.
+
+<Page 1>
+Visualize the election result.
+
+NOTE:
+1. use consistent and default color scheme.
+2. 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.
+"""
+```
+
+It's worth noting that, a more structured user request is also more machine readable.
+
+- Top down instruction can help Vizro-AI to make better plans on what to build.
+- Using line breaks and special characters can help in making instructions clearer for a language model. It helps in parsing and understanding the structure and emphasis in your request.
+
+## 5. Call Vizro-AI
+
+Next, submit the data and prompt string:
+
+```py
+dashboard = vizro_ai.dashboard([df1, df2], user_question)
+```
+
+The call to `dashboard()` triggers the dashboard building process. Once Vizro-AI finishes the dashboard generation process, you can launch the dashboard with `build()`.
+
+!!! example "Generated dashboard"
+
+    === "Code"
+        ```py
+        Vizro().build(dashboard).run()
+        ```
+
+    === "Page1"
+        [![VizroAIDashboardPage1]][VizroAIDashboardPage1]
+
+    === "Page2"
+        [![VizroAIDashboardPage2]][VizroAIDashboardPage2]
+
+    [VizroAIDashboardPage1]: ../../assets/user_guides/dashboard/dashboard1_page1.png
+    [VizroAIDashboardPage2]: ../../assets/user_guides/dashboard/dashboard1_page2.png