Merge branch 'main' into dev/fix-assets-pathname

vizro-core/changelog.d/20231106_165628_antony.milne_jupyter_and_deployment.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/pages/development/contributing.md

@@ -28,7 +28,7 @@ We use [Hatch](https://hatch.pypa.io/) as a project management tool. To get star
 
 !!!note
 
-    The above steps are all automated in GitHub Codespaces thanks to the [devcontainer configuration](.devcontainer/devcontainer.json), and the example dashboard should already be running on port `8050`.
+    The above steps are all automated in GitHub Codespaces thanks to the [devcontainer configuration](https://github.com/mckinsey/vizro/blob/main/.devcontainer/devcontainer.json), and the example dashboard should already be running on port `8050`.
 
     If you haven't used Hatch before, it's well worth skimming through [their documentation](https://hatch.pypa.io/), in particular the page on [environments](https://hatch.pypa.io/latest/environment/). Run `hatch env show` to show all of Hatch's environments and available scripts, and take a look at [`hatch.toml`](https://github.com/mckinsey/vizro/tree/main/vizro-core/hatch.toml) to see our Hatch configuration. It is useful handy to [Hatch's tab completion](https://hatch.pypa.io/latest/cli/about/#tab-completion) to explore the Hatch CLI.
 

vizro-core/docs/pages/user_guides/integration.md

@@ -15,23 +15,48 @@ To install Vizro with Kedro support, run:
 pip install vizro[kedro]
 ```
 
-### Using datasets from the Kedro data catalog
-Given a Kedro data catalog (either from a kedro project or a `catalog.yml` style file), you can use the following code to
-register the datasets with [`kedro_datasets.pandas`](https://docs.kedro.org/en/stable/kedro_datasets.html) type to Vizro's data manager.
+### Using datasets from the Kedro Data Catalog
+`vizro.integrations.kedro` provides functions to help generate and process a [Kedro Data Catalog](https://docs.kedro.org/en/stable/data/index.html). Given a Kedro Data Catalog `catalog`, the general pattern to add datasets into the [Vizro Data Manager][vizro.managers._data_manager] is:
+```python
+from vizro.integrations import kedro as kedro_integration
+from vizro.managers import data_manager
 
-!!! example "Kedro Data Catalog"
-    === "app.py (kedro project)"
+
+for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
+    data_manager[dataset_name] = dataset
+```
+
+This imports all datasets of type [`kedro_datasets.pandas`](https://docs.kedro.org/en/stable/kedro_datasets.html) from the Kedro `catalog` into the Vizro `data_manager`.
+
+The `catalog` variable may have been created in a number of different ways:
+
+1. Kedro project path. Vizro exposes a helper function `vizro.integrations.kedro.catalog_from_project` to generate a `catalog` given the path to a Kedro project.
+2. [Kedro Jupyter session](https://docs.kedro.org/en/stable/notebooks_and_ipython/kedro_and_notebooks.html). This automatically exposes `catalog`.
+3. Data Catalog configuration file (e.g. `catalog.yaml`). This can create a `catalog` entirely independently of a Kedro project using [`kedro.io.DataCatalog.from_config`](https://docs.kedro.org/en/stable/kedro.io.DataCatalog.html#kedro.io.DataCatalog.from_config).
+
+The full code for these different cases is given below.
+
+!!! example "Import a Kedro Data Catalog to the Vizro Data Manager"
+    === "app.py (Kedro project path)"
         ```py
         from vizro.integrations import kedro as kedro_integration
         from vizro.managers import data_manager
 
 
-        catalog = kedro_integration.catalog_from_project("/path/to/projects/iris")
+        catalog = kedro_integration.catalog_from_project("/path/to/kedro/project")
 
         for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
             data_manager[dataset_name] = dataset
         ```
-    === "app.py (use data catalog file YAML syntax without a kedro project)"
+    === "app.ipynb (Kedro Jupyter session)"
+        ```py
+        from vizro.managers import data_manager
+
+
+        for dataset_name, dataset in kedro_integration.datasets_from_catalog(catalog).items():
+            data_manager[dataset_name] = dataset
+        ```
+    === "app.py (Data Catalog configuration file)"
         ```py
         from kedro.io import DataCatalog
         import yaml
@@ -47,7 +72,6 @@ register the datasets with [`kedro_datasets.pandas`](https://docs.kedro.org/en/s
         ```
 
 
-
 ???+ warning
 
     Please note that users of this package are responsible for the content of any custom-created component,

vizro-core/docs/pages/user_guides/run.md

@@ -2,9 +2,9 @@
 
 This guide shows you how to launch your dashboard in different ways. By default, your dashboard apps run on localhost.
 
-## Default built-in web server in flask
+## Default built-in Flask web server
 
-!!! example "Default flask server"
+!!! example "Default built-in Flask web server"
     === "app.py"
         ```py
         from vizro import Vizro
@@ -34,8 +34,8 @@ Dash is running on http://127.0.0.1:8050/
  * Debug mode: on
 ```
 
-## Launch it in jupyter environment
-The dashboard application can be launched in jupyter environment in `inline`, `external`, and `jupyterlab` mode.
+## Jupyter
+The dashboard application can be launched in a Jupyter environment in `inline`, `external`, and `jupyterlab` mode.
 !!! example "Run in jupyter notebook in inline mode"
     === "app.ipynb"
         ```py linenums="1"
@@ -59,10 +59,11 @@ The dashboard application can be launched in jupyter environment in `inline`, `e
 - you can specify `jupyter_mode="external"` and a link will be displayed to direct you to the localhost where the dashboard is running.
 - you can use tab mode by `jupyter_mode="tab"` to automatically open the app in a new browser
 
-## Launch it via Gunicorn
+## Gunicorn
 !!!warning "In production"
-    In production, it is recommended **not** to use the default flask server. One of the options here is gunicorn. It is easy to scale the application to serve more users or run more computations, run more "copies" of the app in separate processes.
-!!! example "Use gunicorn"
+    In production, it is recommended **not** to use the default Flask server. One of the options here is Gunicorn. It is easy to scale the application to serve more users or run more computations, run more "copies" of the app in separate processes.
+
+!!! example "Use Gunicorn"
     === "app.py"
         ```py
         from vizro import Vizro
@@ -80,24 +81,22 @@ The dashboard application can be launched in jupyter environment in `inline`, `e
 
         dashboard = vm.Dashboard(pages=[page])
         app = Vizro().build(dashboard)
-        server = app.dash.server
+        server = app.dash.server # (1)!
         ```
-You need to expose the server via `app.dash.server` in order to use gunicorn as your wsgi here.
-Run it via
+
+        1.  Expose the underlying Flask app through `app.dash.server`.
+
+To run using Gunicorn with four worker processes, execute
 ```bash
-gunicorn app:server --workers 3
+gunicorn app:server --workers 4
 ```
-in the cmd. For more gunicorn configuration, please refer to [gunicorn docs](https://docs.gunicorn.org/en/stable/configure.html)
+in the command line. For more Gunicorn configuration options, please refer to [Gunicorn documentation](https://docs.gunicorn.org/).
 
+## Deployment
 
-## Deployment of Vizro app
-In general, Vizro is returning a Dash app. So if you want to deploy a Vizro app, similar steps apply as if you were to deploy a Dash app.
-For more details, see the docs on [Dash for deployment](https://dash.plotly.com/deployment#heroku-for-sharing-public-dash-apps).
+A Vizro app wraps a Dash app, which itself wraps a Flask app. Hence to deploy a Vizro app, similar guidance applies as for the underlying frameworks:
 
-For reference (where app is a Dash app):
+- [Flask deployment documentation](https://flask.palletsprojects.com/en/2.0.x/deploying/)
+- [Dash deployment documentation](https://dash.plotly.com/deployment)
 
-| Vizro                          | Dash                            |
-|:-------------------------------|:--------------------------------|
-| Vizro()                        | app                             |
-| Vizro().build(dashboard)       | app (after creating app.layout) |
-| Vizro().build(dashboard).run() | app.run()                       |
+In particular, `app = Vizro()` exposes the Flask app through `app.dash.server`. As in the [above example with Gunicorn](#gunicorn), this provides the application instance to a WSGI server.