mckinsey · huong-li-nguyen · Jun 21, 2024 · Jun 18, 2024 · Jun 18, 2024 · Jun 19, 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))
+
+-->
@@ -14,27 +14,27 @@ 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/) </br>
-    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/quickstart/)
+    [:octicons-arrow-right-24: Install Vizro-AI](pages/user-guides/install.md) </br>
+    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/quickstart.md)
 
 
 - :fontawesome-solid-keyboard:{ .lg .middle } __Get hands-on__
 
     ---
 
-    [:octicons-arrow-right-24: Ways to run Vizro-AI](pages/user-guides/run-vizro-ai/)</br>
-    [:octicons-arrow-right-24: Customize models](pages/user-guides/customize-vizro-ai/)</br>
-    [:octicons-arrow-right-24: Create advanced charts](pages/user-guides/create-advanced-charts/)</br>
-    [:octicons-arrow-right-24: Use different languages](pages/user-guides/use-different-languages/)</br>
-    [:octicons-arrow-right-24: Add charts to a dashboard](pages/user-guides/add-generated-chart-usecase/)
+    [: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: 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)
 
 - :material-format-font:{ .lg .middle } __Find out more__
 
     ---
 
-    [:octicons-arrow-right-24: FAQs](pages/explanation/faq/) </br>
-    [:octicons-arrow-right-24: Safeguard dynamic code execution](pages/explanation/safeguard/) </br>
-    [:octicons-arrow-right-24: Guidelines for use of LLMs](pages/explanation/safety-in-vizro-ai//)
+    [:octicons-arrow-right-24: FAQs](pages/explanation/faq.md) </br>
+    [:octicons-arrow-right-24: Safeguard dynamic code execution](pages/explanation/safeguard.md) </br>
+    [:octicons-arrow-right-24: Guidelines for use of LLMs](pages/explanation/safety-in-vizro-ai.md)
 
 - :fontawesome-solid-chart-column:{ .lg .middle } __Vizro__
 

@@ -33,7 +33,7 @@ You can use Vizro-AI in any standard development environment by creating a `.py`
 
 ??? note "Note: API key"
 
-    Make sure you have followed [LLM setup guide](../user-guides/install.md#large-language-model) and
+    Make sure you have followed [LLM setup guide](../user-guides/install.md#set-up-access-to-a-large-language-model) and
     your API key is set up in the environment where your `.py` script is running with command as below:
 
     ```bash

@@ -45,11 +45,10 @@ update-snyk-requirements = "python ../tools/generate_snyk_requirements.py {args}
 
 [envs.docs]
 dependencies = [
-  "mkdocs",
+  "mkdocs>=1.6",
   "mkdocs-material",
   "mkdocs-git-revision-date-localized-plugin",
   "mkdocstrings[python]",
-  "mkdocstrings-python<1.10.4",
   "linkchecker"
 ]
 detached = true
@@ -60,7 +59,7 @@ build = "mkdocs build --strict"
 # more advanced settings using a linkcheckerrc config file. openai.com doesn't seem to work well with linkchecking,
 # throwing 403 errors, but these are not real errors.
 link-check = "linkchecker site --check-extern --no-warnings --ignore=404.html --ignore-url=127.0.0.1 --ignore-url=https://vizro.readthedocs.io/ --ignore-url=https://platform.openai.com/docs/models --ignore-url=openai.com --ignore-url=https://openai.com/"
-serve = "mkdocs serve --strict"
+serve = "mkdocs serve --open"
 
 [envs.lint]
 dependencies = [

@@ -1,5 +1,5 @@
 site_name: Vizro-AI
-site_url: https://vizro-ai.readthedocs.io/en/latest/
+site_url: https://vizro.readthedocs.io/projects/vizro-ai
 nav:
   - Vizro-AI: index.md
   - Tutorials:
@@ -100,3 +100,11 @@ plugins:
 
 extra_css:
   - stylesheets/extra.css
+
+# Strictest settings possible, and will be elevated to ERROR when run with --strict.
+# See https://www.mkdocs.org/user-guide/configuration/#validation.
+validation:
+  omitted_files: warn
+  absolute_links: warn
+  unrecognized_links: warn
+  anchors: warn
@@ -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))
+
+-->
@@ -8,47 +8,47 @@ Vizro is a toolkit for creating modular data visualization applications.
 
     ---
 
-    [:octicons-arrow-right-24: Install Vizro](pages/user-guides/install/) </br>
-    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/first-dashboard/)
+    [:octicons-arrow-right-24: Install Vizro](pages/user-guides/install.md) </br>
+    [:octicons-arrow-right-24: Quickstart tutorial](pages/tutorials/first-dashboard.md)
 
 
 
 -   :fontawesome-solid-keyboard:{ .lg .middle } __Vizro features__
 
     ---
 
-    [:octicons-arrow-right-24: Fundamentals](pages/user-guides/dashboard/)</br>
-    [:octicons-arrow-right-24: Components overview](pages/user-guides/components/)</br>
-    [:octicons-arrow-right-24: Filters, parameters and selectors](pages/user-guides/filters/)</br>
-    [:octicons-arrow-right-24: Visual formatting](pages/user-guides/layouts/)
+    [:octicons-arrow-right-24: Fundamentals](pages/user-guides/dashboard.md)</br>
+    [:octicons-arrow-right-24: Components overview](pages/user-guides/components.md)</br>
+    [:octicons-arrow-right-24: Filters, parameters and selectors](pages/user-guides/filters.md)</br>
+    [:octicons-arrow-right-24: Visual formatting](pages/user-guides/layouts.md)
 
 
 
 -   :fontawesome-solid-microscope:{ .lg .middle } __Hands-on code__
 
     ---
 
-    [:octicons-arrow-right-24: Tutorials](pages/tutorials/explore-components/) <br/>
-    [:octicons-arrow-right-24: Examples](pages/examples/examples/)
+    [:octicons-arrow-right-24: Tutorials](pages/tutorials/explore-components.md) <br/>
+    [:octicons-arrow-right-24: Examples](pages/examples/examples.md)
 
 
 
 -   :material-scale-balance:{ .lg .middle } __FAQs__
 
     ---
 
-    [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq/#how-does-vizro-differ-from-dash-or-streamlit) <br/>
-    [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq/) <br/>
-    [:octicons-arrow-right-24: Where can I ask a question?](pages/explanation/contributing/#got-a-vizro-question) <br/>
+    [:octicons-arrow-right-24: How is Vizro different to Streamlit?](pages/explanation/faq.md/#how-does-vizro-differ-from-dash-or-streamlit) <br/>
+    [:octicons-arrow-right-24: Other FAQs](pages/explanation/faq.md) <br/>
+    [:octicons-arrow-right-24: Where can I ask a question?](pages/explanation/contributing.md/#got-a-vizro-question) <br/>
 
 
 
 -   :fontawesome-solid-hands-holding-circle:{ .lg .middle } __Get involved__
 
     ---
 
-    [:octicons-arrow-right-24: Contribute code](pages/explanation/contributing/) <br/>
-    [:octicons-arrow-right-24: Contribute to our docs](pages/explanation/documentation-style-guide/)
+    [:octicons-arrow-right-24: Contribute code](pages/explanation/contributing.md) <br/>
+    [:octicons-arrow-right-24: Contribute to our docs](pages/explanation/documentation-style-guide.md)
 
 -   :fontawesome-solid-chart-column:{ .lg .middle } __Vizro-AI__
 

@@ -25,7 +25,7 @@ We use [Hatch](https://hatch.pypa.io/) as a project management tool. To get star
 1. [Install `hatch`](https://hatch.pypa.io/latest/install/) by running `brew install hatch` or `pipx install hatch` (preferable to `pip install hatch`).
 2. Clone this repository.
 3. Run `hatch -v env create` from the `vizro-core` folder of your cloned repository. This creates Hatch's `default` environment with dependencies installed and the project installed in development mode (that is, using `pip install --editable`). It will take a few minutes to complete. All following commands should be executed from this folder as well.
-4. Run `hatch run example` to [open an example Vizro dashboard](#examples) with [Dash dev tools](https://dash.plotly.com/devtools) enabled.
+4. Run `hatch run example` to [open an example Vizro dashboard](../examples/examples.md) with [Dash dev tools](https://dash.plotly.com/devtools) enabled.
 5. Edit the code! Thanks to Dash dev tools' hot reloading, any changes to the example app or `vizro` source code should automatically show in your dashboard without needing refresh or restart any process.
 
 !!!note

@@ -575,7 +575,7 @@ Unlike the static text card `vm.Card`, a KPI card must be created using a figure
 Unlike the static text card `vm.Card`, a KPI card must be created using a figure function,
 which enables the text content of the KPI to change based on input from controls or actions.
 
-For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#create-kpi-cards).
+For detailed examples on how to create a KPI card, refer to the [figure user guide on KPI cards](figure.md#key-performance-indicator-kpi-cards).
 
 ## Buttons
 

@@ -2,7 +2,7 @@
 
 This guide demonstrates the usage of custom actions, an idea that shares similarities with, but is not identical to [callbacks](https://dash.plotly.com/basic-callbacks) in `Dash`.
 If you want to use the [`Action`][vizro.models.Action] model to perform functions that are not available in the [pre-defined action functions][vizro.actions], you can create your own custom action.
-Like other [actions](actions.md), custom actions could also be added as an element inside the [actions chain](actions.md#actions-chaining), and it can be triggered with one of many dashboard components.
+Like other [actions](actions.md), custom actions could also be added as an element inside the [actions chain](actions.md#chain-actions), and it can be triggered with one of many dashboard components.
 
 <!-- vale off -->
 ## Simple custom actions

@@ -190,17 +190,17 @@ If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a
 
 ## Add a dashboard logo
 
-Vizro will [automatically incorporate the dashboard logo](assets.md/#logo-image) in the top-left corner of each page if an image named `logo.<extension>` is present within the assets folder.
+Vizro will [automatically incorporate the dashboard logo](assets.md/#add-a-logo-image) in the top-left corner of each page if an image named `logo.<extension>` is present within the assets folder.
 
 ![Dashboard with logo](../../assets/user_guides/dashboard/dashboard_with_logo.png)
 
 ## Browser title
 
-The [website icon](assets.md/#changing-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
+The [website icon](assets.md/#change-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's
 title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage".
 
 ## Meta tags for social media
 
 Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat
-clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#meta-tags-image) and
+clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#include-a-meta-tags-image) and
 [Page `description`][vizro.models.Page] (if supplied).  To see an example, try sharing the [Vizro demo app](https://vizro.mckinsey.com/).
@@ -12,7 +12,7 @@ If these more specific models already achieve what you need then they should be
 the more generic `Figure`. Remember that it is possible to supply [custom charts](custom-charts.md) to `Graph`
 and [custom tables](custom-tables.md) to `Table`.
 
-There are already a few figure functions you can reuse, see the section on [KPI Cards](#kpi-key-performance-indicator-cards)
+There are already a few figure functions you can reuse, see the section on [KPI Cards](#key-performance-indicator-kpi-cards)
 for more details:
 
 - [`kpi_card`][vizro.figures.kpi_card]
@@ -125,7 +125,7 @@ It is a common visual component to display key metrics in a dashboard. Vizro sup
 by performing an aggregation function (by default, `sum`) over a specified column.
 Required arguments are `data_frame` and `value_column`.
 
-- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_with_reference): A KPI card that shows a single value
+- [`kpi_card_with_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference): A KPI card that shows a single value
 and a delta comparison to a reference value found by performing an aggregation function (by default, `sum`) over the specified columns.
 Required arguments are `data_frame`, `value_column` and `reference_column`.
 
@@ -204,7 +204,7 @@ possible with the built-in functions then you can create a [custom figure](custo
         ```
 
         1. For more information, refer to the API reference for the  [`kpi_card`](../API-reference/figure-callables.md#vizro.figures.kpi_card).
-        2. For more information, refer to the API reference for the  [`kpi_card_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_with_reference).
+        2. For more information, refer to the API reference for the  [`kpi_card_reference`](../API-reference/figure-callables.md#vizro.figures.kpi_card_reference).
         3. This creates a [`layout`](layouts.md) with four rows and columns. The KPI cards are positioned in the first eight cells, while the remaining cells are empty.
 
     === "app.yaml"

@@ -3,7 +3,7 @@
 The [`Page`][vizro.models.Page] model accepts a `layout` argument that allows for custom arrangement of charts and components on the screen. This guide shows how to customize the grid specifications in the [`Layout`][vizro.models.Layout].
 
 ## The default layout
-The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#stack-components) on the page in one column.
+The `layout` argument of the [`Page`][vizro.models.Page] model is optional. If no layout is specified, all charts/components are automatically [**stacked vertically**](layouts.md#vertical-and-horizontal-stacking) on the page in one column.
 If you are happy with that arrangement, you can create your charts/components without providing a [`Layout`][vizro.models.Layout].
 
 !!! example "Default Layout"

@@ -76,7 +76,7 @@ By default, if the `navigation` argument is not specified, Vizro creates a navig
 
 ## Include a subset of pages
 
-If you wish to include only some of your dashboard pages in your navigation then list them in the `pages` argument of the `Navigation` model. To refer to a page inside the `Navigation` model, you should always use the page's `id`, which [defaults to the page `title`](pages.md#customizing-the-page-url), we specify `pages = ["My first page", "My second page"]` rather than `pages=[page_1, page_2]`.
+If you wish to include only some of your dashboard pages in your navigation then list them in the `pages` argument of the `Navigation` model. To refer to a page inside the `Navigation` model, you should always use the page's `id`, which [defaults to the page `title`](pages.md#customize-the-page-url), we specify `pages = ["My first page", "My second page"]` rather than `pages=[page_1, page_2]`.
 
 !!! example "Navigation with only some pages"
     === "app.py"
@@ -184,7 +184,7 @@ Under the hood, [`NavBar`][vizro.models.NavBar] uses [`NavLink`][vizro.models.Na
 
 ### `NavLink` examples
 
-The same configuration for [grouping pages](#grouping-your-pages) applies inside a `NavLink`:
+The same configuration for [grouping pages](#group-pages) applies inside a `NavLink`:
 
 !!! example "Accordions inside a `Navlink`"
     === "app.py"

@@ -211,7 +211,7 @@ to format displayed strings automatically.
 
 As mentioned above, all [parameters of the Dash AG Grid](https://dash.plotly.com/dash-ag-grid/reference) can be entered as keyword arguments. Below you can find
 an example of a styled AG Grid where some conditional formatting is applied, and where the columns are editable, but not filterable or resizable.
-There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](./assets.md#Overwrite CSS properties in selective components).
+There are more ways to alter the grid beyond this showcase. AG Grid, like any other Vizro component, can be customized using custom CSS. You can find information in the [guide to overwriting CSS properties](./assets.md#overwrite-css-properties-in-selective-components).
 
 ??? example "Styled and modified Dash AG Grid"