Update user guides and implement branch name prefix enforcement

.pre-commit-config.yaml

@@ -22,6 +22,11 @@ repos:
         entry: tools/find_forbidden_words_in_repo.sh
         language: script
         pass_filenames: false
+      - id: check-branch-name
+        name: check-branch-name
+        entry: tools/check_branch_name.sh
+        language: script
+        pass_filenames: false
 
   - repo: https://github.com/codespell-project/codespell
     rev: v2.2.6

pyproject.toml

@@ -14,7 +14,6 @@ target-version = ["py38"]
 
 [tool.codespell]
 builtin = "clear,rare,en-GB_to_en-US"
-dictionary = "tools/forbidden_words.txt"
 ignore-words-list = "grey"
 
 [tool.mypy]

tools/check_branch_name.sh

@@ -0,0 +1,10 @@
+#!/bin/sh
+
+BRANCH_LOCAL=$(git symbolic-ref --short HEAD)
+BRANCH_CI=${GITHUB_HEAD_REF:-${GITHUB_REF#refs/heads/}}
+REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci|tidy)\/[^/]+(/[^/]+)*)$"
+
+if ! [[ $BRANCH_LOCAL =~ $REGEX ]]  && [[ $BRANCH_CI =~ $REGEX ]]; then
+  echo "Branch name is invalid - please rename your branch following this regex syntax: $REGEX"
+  exit 1
+fi

vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md

@@ -0,0 +1,42 @@
+<!--
+A new scriv changelog fragment.
+
+Uncomment the section that is right (remove the HTML comment wrapper).
+-->
+
+<!--
+### Removed
+
+- A bullet item for the Removed category.
+
+-->
+<!--
+### Added
+
+- A bullet item for the Added category.
+
+-->
+<!--
+### Changed
+
+- A bullet item for the Changed category.
+
+-->
+<!--
+### Deprecated
+
+- A bullet item for the Deprecated category.
+
+-->
+<!--
+### Fixed
+
+- A bullet item for the Fixed category.
+
+-->
+<!--
+### Security
+
+- A bullet item for the Security category.
+
+-->

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

@@ -1,16 +1,23 @@
 # How to create custom charts
 
 This guide shows you how to create custom charts and how to add them to your dashboard.
-
 The [`Graph`][vizro.models.Graph] model accepts the `figure` argument, where you can enter _any_ [`plotly.express`](https://plotly.com/python/plotly-express/) chart as explained in the user guide on [components][graph].
 
-We always recommend starting with [`plotly.express`](https://plotly.com/python/plotly-express/) charts first, but in case that none of the available charts fulfill your requirements, you can also use any custom created [`plotly.graph_objects.Figure()`](https://plotly.com/python/graph-objects/) object (in short `go.Figure()`). It is equally possible to _enhance_ the resulting `go.Figure()` of a `plotly.express` function call. In general, custom/customized charts need to obey the following conditions:
+## Overview of custom charts
+
+In general, the usage of the custom chart decorator `@capture("graph")` is required if your plotly chart requires any post-update calls or customization.
+
+### When to use a custom chart
+
+- If you want to use any of the post figure update calls by `plotly` e.g., `update_layout`, `update_xaxes`, `update_traces`, etc. (for more details, see the docs on [plotly's update calls](https://plotly.com/python/creating-and-updating-figures/#other-update-methods))
+- If you want to use a custom-created [`plotly.graph_objects.Figure()`](https://plotly.com/python/graph-objects/) object (in short, `go.Figure()`) and add traces yourself via [`add_trace`](https://plotly.com/python/creating-and-updating-figures/#adding-traces)
+
+### Requirements of a custom chart function
 
-!!! note "Conditions for using any `go.Figure()` in [`Graph`][vizro.models.Graph]"
-    - a `go.Figure()` object is returned by a function
-    - this function must be decorated with the `@capture("graph")` decorator
-    - this function accepts a `data_frame` argument (of type `pandas.DataFrame`)
-    - the visualization is derived from and requires only one `pandas.DataFrame` (e.g. any further dataframes added through other arguments will not react to dashboard components such as `Filter`)
+- a `go.Figure()` object is returned by the function
+- the function must be decorated with the `@capture("graph")` decorator
+- the function accepts a `data_frame` argument (of type `pandas.DataFrame`)
+- the visualization is derived from and requires only one `pandas.DataFrame` (e.g. any further dataframes added through other arguments will not react to dashboard components such as `Filter`)
 
 The below minimal example can be used as a base to build more sophisticated charts.
 

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

@@ -1,9 +1,14 @@
 # How to create custom components
 
-This guide shows you how to create custom components or enhance existing ones. What is a component? A component in this context would be any of the currently existing models such as e.g. [`Filter`][vizro.models.Filter], [`Parameter`][vizro.models.Parameter], etc.
+If you can't find a component that you would like to have in the code basis, you can easily create your own custom component.
+This guide shows you how to create custom components or enhance existing ones.
+
+In general, you can create a custom component based on any dash-compatible component (e.g. [dash-core-components](https://dash.plotly.com/dash-core-components),
+[dash-bootstrap-components](https://dash-bootstrap-components.opensource.faculty.ai/), [dash-html-components](https://github.com/plotly/dash/tree/dev/components/dash-html-components), etc.).
+
 
 !!!warning
-    When creating your own custom components, you are responsible for the security of your creation. Vizro cannot guarantee
+    When creating your own custom components, you are responsible for the security of your component (e.g. prevent setting HTML from code which might expose users to cross-site scripting). Vizro cannot guarantee
     the security of custom created components, so make sure you keep this in mind when publicly deploying your dashboard.
 
 

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

@@ -88,3 +88,16 @@ Run it via
 gunicorn app:server --workers 3
 ```
 in the cmd. For more gunicorn configuration, please refer to [gunicorn docs](https://docs.gunicorn.org/en/stable/configure.html)
+
+
+## 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).
+
+For reference (where app is a Dash app):
+
+| Vizro                          | Dash                            |
+|:-------------------------------|:--------------------------------|
+| Vizro()                        | app                             |
+| Vizro().build(dashboard)       | app (after creating app.layout) |
+| Vizro().build(dashboard).run() | app.run()                       |