[Docs] Add py.cafe to the docs examples (#569)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Jo Stichbury <[email protected]>
Co-authored-by: Li Nguyen <[email protected]>

.vale/styles/Microsoft/Headings.yml

@@ -72,6 +72,7 @@ exceptions:
   - Pandas
   - Plotly
   - Pydantic
+  - Py.Cafe
   - Python
   - QuantumBlack
   - QuantumBlack Labs

vizro-core/changelog.d/20240705_173826_maximilian_schulz_pycafe_embedding.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/index.md

@@ -8,8 +8,9 @@ Vizro is a toolkit for creating modular data visualization applications.
 
     ---
 
-    [:octicons-arrow-right-24: Install Vizro](pages/user-guides/install.md) </br>
-    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/first-dashboard.md)
+    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/first-dashboard.md) </br>
+    [:octicons-arrow-right-24: Install Vizro](pages/user-guides/install.md)
+
 
 
 

vizro-core/docs/pages/tutorials/explore-components.md

@@ -4,9 +4,11 @@ In this tutorial, we walk through the process of creating a sophisticated dashbo
 
 If you haven't yet done so, you may want to review the [first dashboard tutorial](../tutorials/first-dashboard.md) before starting on this one.
 
-## 1. Install Vizro and get ready to run your code
+## 1. (Optional) Install Vizro and get ready to run your code
 
-To get started with this tutorial, make sure you have [installed Vizro](../user-guides/install.md), and can run the dashboard code within a Jupyter Notebook cell or from a Python script.
+The code for this tutorial is all available for you to experiment with in [Py.Cafe](https://py.cafe/) so there is no need to install Vizro and run it locally.
+
+However, if you prefer working in a Notebook or Python script, you should [install Vizro](../user-guides/install.md).
 
 ## 2. Create a first dashboard page
 
@@ -23,9 +25,10 @@ The code below shows the steps necessary to add a box plot to the page:
 1. Add a Vizro [`Graph`][vizro.models.Graph] to the `components` list.
 2. Add a [`plotly.express.box`](https://plotly.com/python-api-reference/generated/plotly.express.box.html#plotly.express.box) figure to the list of components.
 
+
 !!! example "First component"
     === "app.py"
-        ```py
+        ```{.python pycafe-link}
         from vizro import Vizro
         import vizro.models as vm
         import vizro.plotly.express as px
@@ -40,7 +43,6 @@ The code below shows the steps necessary to add a box plot to the page:
             title="First Page",
             components=[
                 vm.Graph(
-                    id="box_cont",
                     figure=px.box(gapminder_data, x="continent", y="lifeExp", color="continent",
                                     labels={"lifeExp": "Life Expectancy", "continent": "Continent"}),
                 ),
@@ -50,12 +52,15 @@ The code below shows the steps necessary to add a box plot to the page:
         dashboard = vm.Dashboard(pages=[first_page])
         Vizro().build(dashboard).run()
         ```
+
     === "Result"
+
         [![FirstPage1]][FirstPage1]
 
     [FirstPage1]: ../../assets/tutorials/dashboard/dashboard21.png
 
-!!! note "To see the dashboard in action"
+
+??? note "To run the dashboard in a Notebook or script"
 
     Paste the above code into a Notebook cell, run the Notebook, and evaluate it.
 
@@ -69,7 +74,7 @@ The code below shows the steps necessary to add a box plot to the page:
 
     Once the script is running, open your web browser and go to `localhost:8050`. You should see the dashboard page with the gapminder data displayed, as shown in the `Result` tab above.
 
-As you can see from the code, the `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] before building and running it with `Vizro().build(dashboard).run()`. Every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object.
+As you can see from the code, `first_page` is added to the [`Dashboard`][vizro.models.Dashboard] and the dashboard is displayed by running `Vizro().build(dashboard).run()`.
 
 ### 2.2. Add further components
 
@@ -107,9 +112,8 @@ The code below adds two components to the page:
                             "gdpPercap":"GDP Per Cap"}, title=''),
         )
         ```
-
     === "app.py"
-        ```py
+        ```{.python pycafe-link}
         from vizro import Vizro
         import vizro.models as vm
         import vizro.plotly.express as px
@@ -131,12 +135,10 @@ The code below adds two components to the page:
                     """,
                 ),
                 vm.Graph(
-                    id="box_cont",
                     figure=px.box(gapminder_data, x="continent", y="lifeExp", color="continent",
                                     labels={"lifeExp": "Life Expectancy", "continent": "Continent"}),
                 ),
                 vm.Graph(
-                    id="line_gdp",
                     figure=px.line(gapminder_data, x="year", y="gdpPercap", color="continent",
                                     labels={"year": "Year", "continent": "Continent",
                                     "gdpPercap":"GDP Per Cap"}, title=''),
@@ -153,15 +155,14 @@ The code below adds two components to the page:
 
     [FirstPage2]: ../../assets/tutorials/dashboard/dashboard22.png
 
-As you explore the dashboard, you may notice that the current layout could be further enhanced. The charts may appear cramped, while the text component has ample unused space. The next section explains how to configure the layout and arrange the components.
+As you explore the dashboard, you may notice that the current layout could be further enhanced. The charts appear cramped, while the text component has ample unused space. The next section explains how to configure the layout and arrange the components.
 
 !!! note "An introduction to Vizro-AI"
 
     In the example above, the code to create the line graph was generated using [Vizro-AI](https://vizro.readthedocs.io/en/latest/pages/tutorials/first-dashboard/). Vizro-AI enables you to use English, or other languages, to create interactive charts with [Plotly](https://plotly.com/python/) by simplifying the process through use of a large language model. In essence, Vizro-AI generates code from natural language instructions so that you can add it into a Vizro dashboard, such as in the example above.
 
     Find out more in the [Vizro-AI documentation](https://vizro.readthedocs.io/projects/vizro-ai/)!
 
-
 ### 2.3. Configure the layout
 
 By default, Vizro places each element in the order it was added to `components` list, and spaces them equally.
@@ -202,9 +203,8 @@ Run the code below to apply the layout to the dashboard page:
         ```py
         layout=vm.Layout(grid=[[0, 0], [1, 2], [1, 2], [1, 2]])
         ```
-
     === "app.py"
-        ```py
+        ```{.python pycafe-link}
         from vizro import Vizro
         import vizro.models as vm
         import vizro.plotly.express as px
@@ -227,12 +227,10 @@ Run the code below to apply the layout to the dashboard page:
                     """,
                 ),
                 vm.Graph(
-                    id="box_cont",
                     figure=px.box(gapminder_data, x="continent", y="lifeExp", color="continent",
                                     labels={"lifeExp": "Life Expectancy", "continent": "Continent"}),
                 ),
                 vm.Graph(
-                    id="line_gdp",
                     figure=px.line(gapminder_data, x="year", y="gdpPercap", color="continent",
                                     labels={"year": "Year", "continent": "Continent",
                                     "gdpPercap":"GDP Per Cap"}),
@@ -262,7 +260,7 @@ There are two types of control:
 
 The guides on [`How to use Filters`](../user-guides/filters.md) and [`How to use Parameters`](../user-guides/parameters.md) offer instructions on their application. For further customization, refer to the guide on [`How to use selectors`](../user-guides/selectors.md).
 
-To link a control to a component, use the id assigned to the component, which is unique across all dashboard pages and serves as a reference to target it.
+To link a control to a component, use an `id` assigned to the component, which is unique across all dashboard pages and serves as a reference to target it.
 
 To illustrate, let's add a [`Filter`][vizro.models.Filter] on specific
 continents of the underlying gapminder data. The [`Filter`][vizro.models.Filter] requires the `column` argument, that denotes
@@ -278,7 +276,7 @@ are listed in the `targets` parameter, meaning that the filter is be applied to
             ]
         ```
     === "app.py"
-        ```py
+        ```{.python pycafe-link}
         from vizro import Vizro
         import vizro.models as vm
         import vizro.plotly.express as px
@@ -320,6 +318,7 @@ are listed in the `targets` parameter, meaning that the filter is be applied to
         dashboard = vm.Dashboard(pages=[first_page])
         Vizro().build(dashboard).run()
         ```
+
     === "Result"
         [![FirstPage4]][FirstPage4]
 
@@ -336,7 +335,7 @@ Fantastic job! You have completed first dashboard page and gained valuable skill
 
 This section adds a second dashboard page and explains how to use controls and selectors. The new page is structured similarly to the page you created, but contains two charts that visualize the [iris data](https://plotly.com/python-api-reference/generated/plotly.express.data.html#plotly.express.data.iris).
 
-The code below illustrates how to add the page, titled `second_page` to the dashboard by calling `vm.Dashboard(pages=[first_page,second_page])`. There are two `Graph` objects added to the list of components. To enable interactivity on those components, we add two [`Parameters`][vizro.models.Parameter] to the list of `controls`.
+Every [`Page`][vizro.models.Page] that you want to display needs to be added to the [`Dashboard`][vizro.models.Dashboard] object. The code below illustrates how to add the page, titled `second_page` to the dashboard by calling `vm.Dashboard(pages=[first_page,second_page])`. There are two `Graph` objects added to the list of components. To enable interactivity on those components, we add two [`Parameters`][vizro.models.Parameter] to the list of `controls`.
 
 In creating a [`Parameter`][vizro.models.Parameter] object, you define the `target` it applies to. In the code below:
 
@@ -390,7 +389,7 @@ for parameters](../user-guides/parameters.md).
         )
         ```
     === "app.py"
-        ```py
+        ```{.python pycafe-link}
         from vizro import Vizro
         import vizro.models as vm
         import vizro.plotly.express as px
@@ -518,7 +517,7 @@ of the subpages. Additionally, you can use the navigation panel on the left side
             components=[
                 vm.Card(
                     text="""
-                    ![](assets/images/icons/content/collections.svg#icon-top)
+                    ![](https://raw.githubusercontent.com/mckinsey/vizro/786167c822cce65fe85ffad8ed000d8553a5ef44/vizro-core/docs/assets/images/collections.svg#icon-top)
 
                     ### First Page
 
@@ -528,7 +527,7 @@ of the subpages. Additionally, you can use the navigation panel on the left side
                 ),
                 vm.Card(
                     text="""
-                    ![](assets/images/icons/content/features.svg#icon-top)
+                    ![](https://raw.githubusercontent.com/mckinsey/vizro/786167c822cce65fe85ffad8ed000d8553a5ef44/vizro-core/docs/assets/images/features.svg#icon-top)
 
                     ### Second Page
 
@@ -543,7 +542,8 @@ of the subpages. Additionally, you can use the navigation panel on the left side
         dashboard = vm.Dashboard(pages=[home_page, first_page, second_page])
         ```
     === "app.py"
-        ```py
+        ```{.python pycafe-link}
+
         from vizro import Vizro
         import vizro.models as vm
         import vizro.plotly.express as px
@@ -553,7 +553,7 @@ of the subpages. Additionally, you can use the navigation panel on the left side
             components=[
                 vm.Card(
                     text="""
-                    ![](assets/images/icons/content/collections.svg#icon-top)
+                    ![](https://raw.githubusercontent.com/mckinsey/vizro/786167c822cce65fe85ffad8ed000d8553a5ef44/vizro-core/docs/assets/images/collections.svg)
 
                     ### First Page
 
@@ -563,7 +563,7 @@ of the subpages. Additionally, you can use the navigation panel on the left side
                 ),
                 vm.Card(
                     text="""
-                    ![](assets/images/icons/content/features.svg#icon-top)
+                    ![](https://raw.githubusercontent.com/mckinsey/vizro/786167c822cce65fe85ffad8ed000d8553a5ef44/vizro-core/docs/assets/images/features.svg#icon-top)
 
                     ### Second Page