[docs] Close Hacktoberfest docs tickets with fixes for Vale issues (#848

)

Co-authored-by: pre-commit-ci[bot] <66853113+pre-commit-ci[bot]@users.noreply.github.com>
Co-authored-by: Lingyi Zhang <[email protected]>

.vale/styles/Microsoft/Headings.yml

@@ -34,6 +34,7 @@ exceptions:
   - Azure Event Hub
   - CSS
   - CI/CD
+  - Codespaces
   - DataCatalog
   - Data Catalog
   - Data Manager
@@ -55,6 +56,7 @@ exceptions:
   - Google Cloud Functions
   - Graph
   - GraphQL
+  - Hatch
   - Hook
   - Hooks
   - IDs
@@ -68,6 +70,7 @@ exceptions:
   - Kubernetes Pod
   - Kubernetes Service
   - Lambda
+  - LangChain
   - Linux
   - MySQL
   - Notebook

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

@@ -11,6 +11,7 @@ This guide explains the different ways in which you can add a chart generated by
     !!! example "Vizro-AI chart"
 
         === "Code for the cell"
+
             ```py
             import vizro_ai
             from vizro_ai import VizroAI
@@ -61,10 +62,11 @@ This guide explains the different ways in which you can add a chart generated by
         return fig
     ```
 
-The provided `custom_chart` function is an example of the [custom chart](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts), and it returns a `go.Figure()` object.
+The `custom_chart` function is an example of the [custom chart](https://vizro.readthedocs.io/en/stable/pages/user-guides/custom-charts). It returns a `go.Figure()` object.
 This object must then be passed to the `figure` argument of the Vizro [Graph](https://vizro.readthedocs.io/en/stable/pages/user-guides/graph) model.
 
 !!! example "Vizro-AI chart within vizro dashboard"
+
     === "Code for the cell"
         ```py hl_lines="8-23 31"
         from vizro import Vizro
@@ -119,13 +121,14 @@ This object must then be passed to the `figure` argument of the Vizro [Graph](ht
 
 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.
-However, it is important to note that each dashboard run triggers an API call to OpenAI, possibly escalating costs, although this can be avoided if the `fig` object is stored and retrieved as needed, instead of making repeated calls to `plot()`.
+Note that each dashboard run triggers an API call to the LLM, possibly escalating costs. This can be avoided if the `fig` object is stored and retrieved as needed, instead of making repeated calls to `plot()`.
 
 Executing the code below yields the identical dashboard as the example above.
 
 
 !!! example "Use Vizro-AI fig directly in vizro dashboard"
     === "Code for the cell"
+
         ```py hl_lines="13-18 23"
         from vizro import Vizro
         import vizro.models as vm

vizro-ai/docs/pages/user-guides/advanced-options.md

@@ -2,10 +2,13 @@
 
 This guide shows you how to use the advanced options of `VizroAI.plot`.
 
-First we show how to change the input parameters of the function, allowing the control of whether code gets executed, the number of retries of `.plot` when
-it fails validation, and how to change for a more comprehensive return of output (when `return_elements=True`).
+First we show how to change the input parameters of the function, as follows:
 
-Second we show how to use this more comprehensive output, allowing the control of code generation and `fig` object production.
+* control over whether code gets executed,
+* the number of retries of `.plot` when it fails validation,
+* how to request a comprehensive output (when `return_elements=True`).
+
+Second we show how to use this more comprehensive output, enabling control of code generation and `fig` object production.
 
 ## Inputs of `VizroAI.plot`
 
@@ -14,7 +17,7 @@ This is the natural language query from which, together with a data sample, the
 
 
 ### `df`
-Provide any `pandas` data frame to base your query on. The LLM will receive a sample of this data frame to form an appropriate graph.
+Supply any `pandas` data frame to base your query on. The LLM will receive a sample of this data frame to form an appropriate graph.
 
 If the option `validate_code` is set to `True` (which it is by default), the LLM created chart code will be evaluated on a sample of this data frame.
 
@@ -27,14 +30,14 @@ This number determines how often the tool will try to correct an incorrect respo
 ### `return_elements`
 This boolean (by default `False`) determines the return type of `VizroAI.plot`.
 
-If set to `False`, then dynamically generated Python code is executed to produce a `plotly.graph_objects.Figure` object from the LLM response and the user provided data frame. Strictly speaking, it produces a `vizro.charts._charts_utils._DashboardReadyFigure`, which behaves essentially like the former, but is ready to be [inserted](add-generated-chart-usecase.md) into a [Vizro](https://vizro.readthedocs.io/en/stable/) dashboard. It also comes with the default Vizro dark theme.
+If set to `False`, then dynamically generated Python code is executed to produce a `plotly.graph_objects.Figure` object from the LLM response and the user supplied data frame. Strictly speaking, it produces a `vizro.charts._charts_utils._DashboardReadyFigure`, which behaves essentially like the former, but is ready to be [inserted](add-generated-chart-usecase.md) into a [Vizro](https://vizro.readthedocs.io/en/stable/) dashboard. It also comes with the default Vizro dark theme.
 
 If set to `True`, a class (pydantic model) is returned from which the `fig` object, but also various other outputs can be generated. (see below)
 
 ### `validate_code`
 This boolean (by default `True`) determines whether the LLM generated Python code executes with a sample of the data in order to verify that it runs and produces a plotly figure. Be sure [to read and understand what it means when dynamically generated code is executed](../explanation/safety-in-vizro-ai.md#execution-of-dynamic-code-in-vizro-ai).
 <!-- vale on -->
-If `return_elements=True` AND `validate_code=False`, then NO code is executed to obtain the return of `VizroAI.plot`. This means that the code string obtained is not validated, but also that no code was executed.
+If `return_elements=True` **and** `validate_code=False`, then no code is executed to obtain the return of `VizroAI.plot`. This means that the code string obtained is not validated, but also that no code was executed.
 
 ## Output if `return_elements=True`
 
@@ -153,11 +156,14 @@ This `fig` object is a basic plotly figure.
     [VizroAIChartPlotly]: ../../assets/user_guides/VizroAIPlotly.png
 
 #### Using different data
-You can create the `fig` object with different data while ensuring the overall schema remains consistent. You can re-evaluate this function to generate various `fig` objects for different datasets. For example, the code could be generated using fake or sample data fed into Vizro-AI. When moving to production, you can switch the data source to the complete dataset, as long as the data schema is consistent.
+<!--vale off-->
+You can create the `fig` object with different data while ensuring the overall schema remains consistent. You can re-evaluate this function to generate various `fig` objects for different data. For example, the code could be generated using fake or sample data fed into Vizro-AI. When moving to production, you can switch the data source to the complete dataset, as long as the data schema is consistent.
+<!--vale on-->
 
 !!! example "Different data"
 
     === "Code"
+
         ```py
         from vizro_ai import VizroAI
         import plotly.express as px
@@ -180,12 +186,13 @@ You can create the `fig` object with different data while ensuring the overall s
         ```
 
 #### Changing the chart name
-This option executes the chart code with the name provided under `chart_name`. This can be important when you want to avoid overwriting variables in the namespace.
+This option executes the chart code with the name given under `chart_name`. This can be important when you want to avoid overwriting variables in the namespace.
 
 
 !!! example "Changing the `chart_name`"
 
     === "Code"
+
         ```py
         from vizro_ai import VizroAI
         import plotly.express as px

vizro-ai/docs/pages/user-guides/customize-vizro-ai.md

@@ -8,14 +8,14 @@ Vizro-AI supports **any** model that is available via [Langchain's `BaseChatMode
 
 ### Setting model via string for ease of use
 
-We have created shortcuts with sensible defaults (mainly setting `temperature=0`) for some common vendors. These models can be chosen by using the string format in the tabs below. If no model is provided, the default (currently `"gpt-4o-mini"`) is selected.
+We have created shortcuts with sensible defaults (mainly setting `temperature=0`) for some common vendors. These models can be chosen by using the string format in the tabs below. If no model is supplied, the default (currently `"gpt-4o-mini"`) is selected.
 
 ```py
 vizro_ai = VizroAI(model="<chosen model>")
 ```
 
 !!!note
-    For the string settings to work, you must provide your API key via environment variables. The relevant variable names to be set are noted in each vendor tab.
+    For the string settings to work, you must supply your API key via environment variables. The relevant variable names to be set are noted in each vendor tab.
 
 === "OpenAI"
 
@@ -80,7 +80,9 @@ vizro_ai = VizroAI(model="<chosen model>")
 !!!note
     When choosing the string representation, it sometimes can be tricky to have the correct environment variable set for the API key (and potential base URL). In case you cannot get this to work, we recommend instantiating the model directly (see below) and providing the API key via the models parameters.
 
+<!--vale off-->
 ### Setting model via class for additional configuration
+<!--vale on-->
 Beyond passing a string, you can pass **any** model derived from [Langchain's `BaseChatModel` class](https://api.python.langchain.com/en/latest/language_models/langchain_core.language_models.chat_models.BaseChatModel.html#langchain_core.language_models.chat_models.BaseChatModel) that has the [`with_structured_output` method](https://python.langchain.com/v0.2/docs/how_to/structured_output/#the-with_structured_output-method) implemented. An overview of the [most common vendor models supporting this functionality](https://python.langchain.com/v0.2/docs/integrations/chat/) can be found in Langchain's documentation.
 
 When choosing this approach, you can customize your model beyond the chosen default from the string instantiation. The choice of available arguments depends on the specific vendor implementation, but usually the main parameter to tweak is the temperature.
@@ -112,10 +114,10 @@ Passing an instantiated model to `VizroAI` lets you customize it, and additional
 
 ### Chart generation
 
-At the time of writing, we found that for chart creation, some of the leading vendor's "cheaper" models, for example OpenAI's `gpt-4o-mini` and `gpt-3.5` model series, are suitable for basic charting despite their relatively low price points.
+At the time of writing, we found that for chart creation, the leading vendor's "cheaper" models, for example OpenAI's `gpt-4o-mini` and `gpt-3.5` model series, are suitable for basic charting despite their relatively low price points.
 
 Consider upgrading to, in the case of OpenAI the `gpt-4o` and `gpt-4` model series, or in the case of Anthropic the `claude-3-5-sonnet-20240620` model series, for more demanding tasks. The downside of using these models is that they come at a higher cost.
 
 ### Dashboard generation
 
-At the time of writing we find that cheaper models only allow for basic dashboards. For a reasonably complex dashboard we recommend the flagship models of the leading vendors, for example `gpt-4o` or `claude-3-5-sonnet-20240620`.
+At the time of writing we find that cheaper models only work for basic dashboards. For a reasonably complex dashboard we recommend the flagship models of the leading vendors, for example `gpt-4o` or `claude-3-5-sonnet-latest`.

vizro-ai/docs/pages/user-guides/install.md

@@ -113,11 +113,11 @@ To make the OpenAI API key available for all projects, you can set it as a syste
 variable. Refer to the section ["Set up your API key for all projects"](https://platform.openai.com/docs/quickstart/step-2-setup-your-api-key?context=python)
 in the OpenAI documentation. (It is under the dropdown of "Step 2: Set up your API key").
 
-The documentation provides step-by-step instructions for setting up the API key as an environment
+The documentation gives step-by-step instructions for setting up the API key as an environment
 variable, on operating systems including Windows and MacOS.
 
 !!!note
-    Sometimes setting up the `.env` file can be fiddly. If necessary, you can provide the API key directly to the instantiated model. See [our user guide](./customize-vizro-ai.md#setting-model-via-class-for-additional-configuration) for this option. Remember not to commit this API key to any public space!
+    Sometimes setting up the `.env` file can be fiddly. If necessary, you can supply the API key directly to the instantiated model. See [our user guide](./customize-vizro-ai.md#setting-model-via-class-for-additional-configuration) for this option. Remember not to commit this API key to any public space!
 
 __Set the base URL (optional)__
 

vizro-ai/docs/pages/user-guides/retrieve-dashboard-code.md

@@ -1,8 +1,8 @@
 # Retrieve the code of Vizro-AI generated dashboard
 
-This guide shows how to retrieve the code of a Vizro-AI generated dashboard. The code can be used for further iterations, improvements and deployment.
+This guide shows how to retrieve the code of a Vizro-AI generated dashboard. The code can be used for further iterations, improvements, and deployment.
 
-While Vizro-AI can follow complex user requirements well and generate high-quality dashboards, due to the nature of LLMs, the generated dashboards often only approximately match user expectations. Besides refining the user prompt and re-running Vizro-AI, you can also extract the code and iterate manually to achieve the desired result.
+While Vizro-AI can follow complex user requirements well and generate high-quality dashboards, due to the nature of LLMs, the generated dashboards often only partly match user expectations. Besides refining the user prompt and re-running Vizro-AI, you can also extract the code and iterate manually to achieve the desired result.
 
 
 ## 1. Prepare the data and user prompt

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

@@ -64,5 +64,5 @@ You can use Vizro-AI in any standard development environment by creating a `.py`
 ## Application integration
 
 You may prefer to integrate Vizro-AI into an application that offers a UI for users to input prompts. For that you can take the `fig` object from the `.plot` call, and use it elsewhere
-in any application after potentially processing it further (such as serializing it or similar). It is also possible to obtain the code that would produce the object. For any advanced usage options, refer to
+in any application (you might also want to process it further, for example, by serializing it or similar). It is also possible to obtain the code that would produce the object. For any advanced usage options, refer to
 [our advanced options guide](advanced-options.md).

vizro-core/docs/pages/explanation/authors.md

@@ -10,11 +10,11 @@
 [Maximilian Schulz](https://github.com/maxschulz-COL),
 [Nadija Graca](https://github.com/nadijagraca),
 [Petar Pejovic](https://github.com/petar-qb)
-
+<!-- vale on -->
 
 
 ## Previous team members and code contributors
-
+<!-- vale off -->
 [Ann Marie Ward](https://github.com/AnnMarieW),
 [Ned Letcher](https://github.com/ned2),
 Natalia Kurakina,

vizro-core/docs/pages/explanation/contributing.md

@@ -53,7 +53,9 @@ The Hatch commands you need most commonly are as follows. These must be executed
 * [`hatch run docs:serve`](#hatch-run-docsserve) builds and displays documentation that hot-reloads while you edit it. Documentation is also built automatically in your PR and can be previewed on Read The Docs.
 * [`hatch run pip`](#hatch-run-pip) provides a [pip-compatible interface using uv](https://docs.astral.sh/uv/pip/). You should not need to use this much.
 
+<!-- vale off-->
 To save yourself from repeatedly typing `hatch run` you might like to [set up an alias](https://www.tecmint.com/create-alias-in-linux/):
+<!-- vale on-->
 
 ```console
 alias hr="hatch run"
@@ -74,7 +76,7 @@ This enables you to run, for example, `hr lint` instead of `hatch run lint`. On
 
 `hatch run example` runs an example dashboard on port 8050 that hot-reloads while you edit it. On GitHub Codespaces, this [runs automatically on startup](https://docs.github.com/en/codespaces/developing-in-a-codespace/forwarding-ports-in-your-codespace) and is labeled as `scratch_dev example`. On your local machine, you can access the dashboard by pointing your browser to [http://127.0.0.1:8050](http://127.0.0.1:8050).
 
-By default, this command runs the dashboard configured in `vizro-core/examples/scratch_dev/app.py`. This dashboard is used as a temporary "scratch" playground during development. Since it is opened automatically in GitHub Codespaces, it's the perfect place to demonstrate or test out a new feature you're developing. PR reviewers can then immediately see exactly what your changes do by opening a codespace on your branch.
+By default, this command runs the dashboard configured in `vizro-core/examples/scratch_dev/app.py`. This dashboard is used as a temporary "scratch" playground during development. Since it is opened automatically in GitHub Codespaces, it's the perfect place to show, or test out, a new feature you're developing. PR reviewers can then immediately see exactly what your changes do by opening a codespace on your branch.
 
 You can run any example in `vizro-core/examples` or its subdirectories by running `hatch run example <example_path>`, where `<example_path>` is the path to the directory containing the `app.py` file relative to `vizro-core/examples`. For example, `hatch run example dev` runs a dashboard located at `vizro-core/examples/dev/app.py`. This dashboard demonstrates a full set of Vizro features and is also [hosted on Hugging Face](https://huggingface.co/spaces/vizro/demo-features).
 
@@ -139,9 +141,13 @@ For more information on our documentation style, refer to our [style guide](docu
 
 `hatch run pip` provides a [pip-compatible interface using uv](https://docs.astral.sh/uv/pip/). You should not need to use this often.
 
-Vizro's dependencies are described by the `dependencies` section in `vizro-core/pyproject.toml`. There is no need to manually install or update the dependencies in your environment; they will be handled automatically for you when you do `hatch run`. This means that there is generally no need to `pip install` anything.
+Vizro's dependencies are described by the `dependencies` section in `vizro-core/pyproject.toml`. There is no need to manually install or update the dependencies in your environment; they will be handled automatically for you when you do `hatch run`. This means that there is usually no need to `pip install` anything.
 
-We have [configured Hatch to use uv](https://hatch.pypa.io/1.12/how-to/environment/select-installer/) for virtual environment creation, dependency resolution and installation. This is extremely fast. If you have installed unwanted dependencies in your Hatch environment then the simplest solution is to delete the environment (`hatch env remove` to remove one environment or `hatch env prune` to remove all environments). Your next `hatch run` command will quickly recreate the environment and install all the dependencies it needs.
+We have [configured Hatch to use uv](https://hatch.pypa.io/1.12/how-to/environment/select-installer/) for rapid virtual environment creation, dependency resolution and installation.
+
+!!! note
+
+    If you have installed unwanted dependencies in your Hatch environment then the simplest solution is to delete the environment (`hatch env remove` to remove one environment or `hatch env prune` to remove all environments). Your next `hatch run` command will recreate the environment and install all the dependencies it needs.
 
 If for some reason you do need to use `pip` then the correct way to do so is through `hatch run pip`. For example, you could run `hatch run pip show plotly`. This will use the version of uv that Hatch itself uses under the hood. If you already have uv installed globally then `uv pip show plotly` would also work.