Update docs

vizro-core/changelog.d/20231108_230816_antony.milne_fix_assets_pathname.md

@@ -16,30 +16,24 @@ Uncomment the section that is right (remove the HTML comment wrapper).
 - 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))
+- `Vizro` takes `**kwargs` that are passed through to `Dash` ([#151](https://github.com/mckinsey/vizro/pull/151))
 
--->
-<!--
 ### 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))
+- The path to a custom assets folder is now configurable using the `assets_folder` argument when instantiating `Vizro` ([#151](https://github.com/mckinsey/vizro/pull/151))
 
--->
 <!--
 ### 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))
+- Assets are now routed correctly when hosting the dashboard in a subdirectory ([#151](https://github.com/mckinsey/vizro/pull/151))
 
--->
 <!--
 ### Security
 

vizro-core/docs/pages/API_reference/vizro.md

@@ -1,3 +1,7 @@
 # Vizro
 
 ::: vizro
+    options:
+      merge_init_into_class: false
+      docstring_options:
+        ignore_init_summary: false

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

@@ -19,11 +19,7 @@ The user-provided `assets` folder thus always takes precedence.
 ```
 
 ## Adding static images
-We leverage Dash's underlying functionalities to embed images into the app.
-For more information, see [here](https://dash.plotly.com/dash-enterprise/static-assets?de-version=5.1#embedding-images-in-your-dash-apps).
-
-For example, you can leverage the `dash.get_asset_url()` function in your custom components, such that any provided path does not require `assets` as a prefix in the relative path anymore.
-
+We use [Dash's underlying functionalities](https://dash.plotly.com/dash-enterprise/static-assets#embedding-images-in-your-dash-apps) to embed images into the app). You should always use `dash.get_asset_url` to refer to files inside your assets folder to ensure that the correct URL is generated in both development and production environments. For example, the file `collections.svg` in the above example would be referenced as `dash.get_asset_url("images/icons/collections.csv")`.
 
 ## Changing the favicon
 To change the default favicon (website icon appearing in the browser tab), add a file named `favicon.ico` to your `assets` folder.
@@ -63,8 +59,6 @@ For reference, all Vizro CSS files can be found [here](https://github.com/mckins
 
         dashboard = vm.Dashboard(pages=[page])
 
-        # only required if assets folder is not located at the same directory of app.py
-        Vizro._user_assets_folder = os.path.abspath("../assets")
 
         Vizro().build(dashboard).run()
         ```
@@ -131,9 +125,6 @@ To achieve this, do the following:
 
         dashboard = vm.Dashboard(pages=[page])
 
-        # only required if assets folder is not located at the same directory of app.py
-        Vizro._user_assets_folder = os.path.abspath("../assets")
-
         Vizro().build(dashboard).run()
         ```
     === "app.yaml"
@@ -164,17 +155,14 @@ To achieve this, do the following:
 
     **Order of CSS being served to app**
 
-    1. Dash styling sheets
-    2. Vizro external styling sheets
-    3. User assets folder
-        - CSS/JS Files
-        - Folders
-           - CSS/JS Files
+    1. Dash built-in stylesheets
+    2. Vizro built-in stylesheets
+    3. User assets folder stylesheets
 
 
 ## Changing the `assets` folder path
 If you do not want to place your `assets` folder in the root directory of your app, you can
-also change the reference to your `assets` folder. Note that the path provided needs to be an absolute path.
+specify an alternative path through the `assets_folder` argument of the [`Vizro`][vizro.Vizro] class.
 
 ```python
 from vizro import Vizro
@@ -183,8 +171,7 @@ import vizro.models as vm
 page = <INSERT CONFIGURATION HERE>
 dashboard = vm.Dashboard(pages=[page])
 
-Vizro._user_assets_folder = "absolute/path/to/assets"
-app = Vizro().build(dashboard).run()
+app = Vizro(assets_folder="path/to/assets/folder").build(dashboard).run()
 
 ```
 

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

@@ -82,9 +82,13 @@ The dashboard application can be launched in a Jupyter environment in `inline`,
         dashboard = vm.Dashboard(pages=[page])
         app = Vizro().build(dashboard)
         server = app.dash.server # (1)!
+
+        if __name__ == "__main__":  # (2)!
+            app.run()
         ```
 
-        1.  Expose the underlying Flask app through `app.dash.server`.
+        1. Expose the underlying Flask app through `app.dash.server`; this will be used by Gunicorn.
+        2. Enable the same app to still be run using the built-in Flask server with `python app.py` for development purposes.
 
 To run using Gunicorn with four worker processes, execute
 ```bash
@@ -100,3 +104,5 @@ A Vizro app wraps a Dash app, which itself wraps a Flask app. Hence to deploy a
 - [Dash deployment documentation](https://dash.plotly.com/deployment)
 
 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.
+
+[`Vizro`][vizro.Vizro] accepts `**kwargs` that are passed through to `Dash`. This allows you to configure the underlying Dash app using the same [argumentst that are available](https://dash.plotly.com/reference#dash.dash) in `Dash`. For example, in a deployment context, you might like to specify a custom `url_base_pathname` to serve your Vizro app at a specific URL rather than at your domain root.

vizro-core/examples/jupyter/app.ipynb

@@ -544,8 +544,7 @@
     "    ]\n",
     ")\n",
     "\n",
-    "Vizro._user_assets_folder = os.path.abspath(\"../assets\")\n",
-    "Vizro().build(dashboard).run()"
+    "Vizro(assets_folder=\"../assets\").build(dashboard).run()"
    ]
   }
  ],

vizro-core/src/vizro/_vizro.py

@@ -16,11 +16,16 @@ class Vizro:
     """The main class of the `vizro` package."""
 
     def __init__(self, **kwargs):
-        """Initializes Dash."""
+        """Initializes Dash app, stored in `self.dash`.
+
+        Args:
+            kwargs: Passed through to `Dash.__init__`, e.g. `assets_folder`, `url_base_pathname`. See
+             [Dash documentation](https://dash.plotly.com/reference#dash.dash) for possible arguments.
+        """
         self.dash = dash.Dash(**kwargs, use_pages=True, pages_folder="")
 
         # Include Vizro assets (in the static folder) as external scripts and stylesheets. We extend self.dash.config
-        # objects so the user can specify additional external_scripts and externaL_stylesheets via kwargs.
+        # objects so the user can specify additional external_scripts and external_stylesheets via kwargs.
         vizro_assets_folder = Path(__file__).with_name("static")
         static_url_path = self.dash.config.requests_pathname_prefix + STATIC_URL_PREFIX
         vizro_css = self._get_external_assets(static_url_path, vizro_assets_folder, "css")
@@ -64,8 +69,8 @@ def run(self, *args, **kwargs):  # if type annotated, mkdocstring stops seeing t
         """Runs the dashboard.
 
         Args:
-            args: Any args to `dash.run_server`
-            kwargs: Any kwargs to `dash.run_server`
+            args: Passed through to `dash.run`.
+            kwargs: Passed through to `dash.run`.
         """
         data_manager._frozen_state = True
         model_manager._frozen_state = True