mckinsey · stichbury · Jul 9, 2024 · Jul 3, 2024 · Jul 3, 2024 · Jul 3, 2024
@@ -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))
+
+-->
@@ -39,9 +39,7 @@ Use of Vizro-AI requires the use of a large language model. At present, we only
 
 To use OpenAI with Vizro-AI you need an API key, which you can get by [creating an OpenAI account if you don't already have one](https://platform.openai.com/account/api-keys).
 
-!!! note
-
-    We recommend that you consult the [third-party API key section of the disclaimer documentation](../explanation/disclaimer.md) documentation.
+We recommend that you consult the [third-party API key section of the disclaimer documentation](../explanation/disclaimer.md) documentation.
 
 There are two common ways to set up the API key in a development environment.
 
@@ -125,12 +123,10 @@ You should see a return output of the form `x.y.z`.
 
 ## Upgrade
 
+Check the [release notes](https://github.com/mckinsey/vizro/blob/main/vizro-ai/CHANGELOG.md) for any notable breaking changes before migrating an existing project.
+
 To change the version of Vizro-AI installed:
 
 ```bash
 pip install -U vizro_ai
 ```
-
-!!! tip Check the Vizro-AI release notes
-
-    To upgrade safely, check the [release notes](https://github.com/mckinsey/vizro/blob/main/vizro-ai/CHANGELOG.md) for any notable breaking changes before migrating an existing project.
@@ -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))
+
+-->
@@ -15,16 +15,14 @@ The dashboard launches with a home page that offers four other pages:
 
 You can find the code for each of the charts, for each page of the dashboard, in the `examples` folder of the `vizro-core` package, within [Vizro's GitHub repository](https://github.com/mckinsey/vizro). The code is available as a [`.py` file](https://github.com/mckinsey/vizro/blob/main/vizro-core/examples/demo/app.py) or as a [Jupyter Notebook](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/demo/jupyter_version).
 
-!!! info
+!!! note
 
     If you have any problems running the example code, please [raise an issue](https://github.com/mckinsey/vizro/issues) on the Vizro repository.
 
 ## Vizro features
 The [`examples/features` folder](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/features) of the `vizro-core` package within [Vizro's GitHub repository](https://github.com/mckinsey/vizro) contains an example that illustrates Vizro's features. The code is available as a Python script, plus there is an alternative `yaml_version` that offers the same example as the pydantic model but via YAML configuration.
 
-!!! info "Ways to configure a dashboard"
-
-    In most cases, the pydantic model should be your preferred method of dashboard configuration, but you can also [define a dashboard with YAML, JSON, or as a Python dictionary](../user-guides/dashboard.md).
+The pydantic model should be your preferred method of dashboard configuration, but you can also [define a dashboard with YAML, JSON, or as a Python dictionary](../user-guides/dashboard.md).
 
 ## Examples from Vizro users
 

@@ -33,17 +33,21 @@ Avoid referring to data using terms like "dataset" or "connector". Prefer to use
 
 ## Call out boxes
 
-Keep the amount of text, and the number and variety of callouts used, to a minimum. There is a [broad set available](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) for use in the Vizro docs, but we prefer to limit usage mostly to the following:
+Keep the amount of text, and the number and variety of callouts used, to a minimum. There is a [broad set available](https://squidfunk.github.io/mkdocs-material/reference/admonitions/#supported-types) for use in the Vizro docs, but we limit usage to notes, warnings, details and examples:
 
-!!!note "note"
+!!! note "note"
 
      For notable information.
 
-!!!warning "warning"
+!!! warning "warning"
 
      To indicate a potential gotcha.
 
-!!!example "example"
+??? details "See more details"
+
+    A side note (used sparingly)
+
+!!! example "example"
 
      For example code.
 
@@ -52,7 +56,7 @@ Callout boxes can be made collapsible: if you use them, add them to the page so
 
 ???+ note "Limit the use of collapsible callouts to secondary information only"
 
-    Don't use expanded-on-load collapsibles. If the callout contains important information and needs to be shown as expanded on page load, it should simply be non-collapsible.
+    Don't use expanded-on-load collapsibles like this one. If the callout contains important information and needs to be shown as expanded on page load, it should simply be non-collapsible.
 
 ## Capitalization
 * Only capitalize proper nouns such as the names of technology products, other tools and services.

@@ -55,7 +55,7 @@ The code below shows the steps necessary to add a box plot to the page:
 
     [FirstPage1]: ../../assets/tutorials/dashboard/dashboard21.png
 
-!!! tip "To see the dashboard in action"
+!!! note "To see the dashboard in action"
 
     Paste the above code into a Notebook cell, run the Notebook, and evaluate it.
 
@@ -155,7 +155,7 @@ The code below adds two components to the page:
 
 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.
 
-!!! tip "An introduction to Vizro-AI"
+!!! 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.
 

@@ -5,19 +5,18 @@ Many components of a dashboard (for example, [`Graph`][vizro.models.Graph] or [`
 
 By combining the [`Action`][vizro.models.Action] model with an action function, you can create complex dashboard interactions triggered by various events.
 
-There are already a few action functions you can reuse.
+There are already a few action functions you can reuse:
 
-???+ info "Overview of currently available pre-defined action functions"
-
-    - [`export_data`][vizro.actions.export_data]
-    - [`filter_interaction`][vizro.actions.filter_interaction]
+- [`export_data`][vizro.actions.export_data]
+- [`filter_interaction`][vizro.actions.filter_interaction]
 
 ## Pre-defined actions
 
 To attach an action to a component, you must enter the [`Action`][vizro.models.Action] model into the component's `action` argument. You can then
 add a desired pre-defined action function into the `function` argument of the [`Action`][vizro.models.Action].
 
 ??? note "Note on `Trigger`"
+
     Currently each component has one pre-defined trigger property. A trigger property is an attribute of the component that triggers a configured action (for example, for the `Button` it is `n_click`).
 
 The below sections are guides on how to use pre-defined action functions.
@@ -128,7 +127,7 @@ Graph(figure=px.scatter(..., custom_data=["continent"]))
 
 Selecting a data point with a corresponding value of "Africa" in the continent column will result in filtering the data of target charts to show only entries with "Africa" in the continent column. The same applies when providing multiple columns in `custom_data`.
 
-!!! tip
+!!! note
     - You can reset your chart interaction filters by refreshing the page
     - You can create a "self-interaction" by providing the source chart id as its own `target`
 

@@ -264,12 +264,12 @@ It's essential to understand the relationship between the targeted CSS class or
     [CardCSS]: ../../assets/user_guides/assets/css_change_card.png
 
 
-??? note "Order of serving CSS files"
+## Order of serving CSS files
 
-    CSS properties will be applied with the last served file taking precedence. The order of serving is:
+CSS properties will be applied with the last served file taking precedence. The order of serving is:
 
-    1. Dash built-in stylesheets
-    2. Vizro built-in stylesheets
-    3. User assets folder stylesheets
+1. Dash built-in stylesheets
+2. Vizro built-in stylesheets
+3. User assets folder stylesheets
 
-    Within each of these categories, individual files are served in alphanumeric order.
+Within each of these categories, individual files are served in alphanumeric order.
@@ -324,21 +324,19 @@ and give an attribute selector to select images with that matching URL hash.
 
     [CardImageStyled]: ../../assets/user_guides/components/card_image_styled.png
 
-???+ tip
+Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
 
-    Use the following pre-defined URL hashes in your image path to apply Vizro's default styling.
-
-    To float the image next to the text:
+* To float the image next to the text:
 
     - floating-left: `![](my_image.png#floating-left)`
     - floating-right: `![](my_image.png#floating-right)`
     - floating-center: `![](my_image.png#floating-center)`
 
-    To apply the default icon styling:
+* To apply the default icon styling:
 
     - icon-top: `![](my_image.png#icon-top)`
 
-??? example "Card with floating image"
+!!! example "Card with floating image"
     === "app.py"
         ```py
         import vizro.models as vm
@@ -402,7 +400,7 @@ and give an attribute selector to select images with that matching URL hash.
 
     [CardImageFloating]: ../../assets/user_guides/components/card_image_floating.png
 
-??? example "Card with icon"
+!!! example "Card with icon"
     === "app.py"
         ```py
         import vizro.models as vm
@@ -462,17 +460,12 @@ img[src*="#my-image"] {
 }
 ```
 
-??? example "Responsive icon"
+!!! example "Responsive icon"
     ![responsive icon](../../assets/user_guides/components/responsive_icon.gif)
 
 ### Create a navigation card
 
-!!! note
-
-    This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation
-    card. To configure the navigation panel on the left hand side of the screen, refer to the
-    [guide on navigation](navigation.md).
-
+This section describes how to use the [`Card`][vizro.models.Card] component to create a navigation card. To configure the navigation panel on the left hand side of the screen, refer to the [guide on navigation](navigation.md).
 
 A navigation card enables you to navigate to a different page via a click on the card area.
 
@@ -561,7 +554,7 @@ To create a navigation card:
 
 If you now click on the card area, you should automatically be redirected to the relevant `href`.
 
-???+ note
+!!! note
 
     When using the [`Card`][vizro.models.Card], keep the following in mind:
 

@@ -8,9 +8,9 @@ A [`Container`][vizro.models.Container] complements the idea of a [`Page`][vizro
 While there is currently no clear difference in rendering, extra functionality will be added to the `Container` soon (including controls specific to that container),
 enhancing the ability to manage related components.
 
-??? note "Displaying multiple containers inside Tabs"
+!!! note "Displaying multiple containers inside Tabs"
 
-    An alternative way for displaying multiple containers on one page is to place them inside [Tabs](tabs.md).
+    An alternative way to display multiple containers on one page is to place them inside [Tabs](tabs.md).
 
     [`Tabs`][vizro.models.Tabs] organize and separate groups of related content in a dashboard, letting users switch between different sections or views.
     They are a way of putting multiple containers into the same screen space, and letting the user switch between them.
@@ -154,9 +154,7 @@ To add a [`Container`][vizro.models.Container] to your page, do the following:
 
     [Container]: ../../assets/user_guides/components/containers.png
 
-!!! note
-
-    Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
+Note that an almost identical layout can also be achieved using solely the [`Page.layout`](layouts.md) by configuring the `Page.layout` as `vm.Layout(grid = [[0, 1], [2, 2]])`.
 
 ## Nested containers
 Containers can be nested, providing a hierarchical structure for organizing components.

@@ -34,9 +34,8 @@ Building on the above, there are several routes one can take. The following exam
 
 To alter the data in the `data_frame` argument, consider using a [Filter](filters.md) or [parametrized data loading](data.md/#parametrize-data-loading) and [dynamic data](data.md/#dynamic-data). The `data_frame` argument input to a custom chart contains the data **after** filters and parameters have been applied.
 
-!!! tip
-
-    Custom charts can be targeted by [Filters](filters.md) or [Parameters](parameters.md) without any additional configuration. We will showcase both possibilities in the following examples. In particular the `Parameters` in combination with custom charts can be highly versatile in achieving custom functionality.
+!!! note
+    Custom charts can be targeted by [Filters](filters.md) or [Parameters](parameters.md) without any extra configuration. We will showcase both possibilities in the following examples.
 
 ## Enhanced `plotly.express` chart with reference line