From 3cfcf0224b6f0a9a09c9ec944dabb8b3ee96e913 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 15:48:49 +0200 Subject: [PATCH 01/14] Add branch name check --- .pre-commit-config.yaml | 5 +++++ tools/check_branch_name.sh | 10 ++++++++++ 2 files changed, 15 insertions(+) create mode 100755 tools/check_branch_name.sh diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 1c266ab55..1147a76a4 100644 --- a/.pre-commit-config.yaml +++ b/.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.4 diff --git a/tools/check_branch_name.sh b/tools/check_branch_name.sh new file mode 100755 index 000000000..7a9b067b1 --- /dev/null +++ b/tools/check_branch_name.sh @@ -0,0 +1,10 @@ +#!/bin/sh + +BRANCH=$(git rev-parse --abbrev-ref HEAD) +REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci)\/[^/]+(/[^/]+)*)$" + + +if ! [[ $BRANCH =~ $REGEX ]]; then + echo "Invalid branch name - please rename your branch following this $REGEX syntax." + exit 1 +fi From 59ac57ec68f1a3d4f45b8968fceb16fa280a64d2 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 16:16:48 +0200 Subject: [PATCH 02/14] Add instructions for post figure update calls --- vizro-core/docs/pages/user_guides/custom_charts.md | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user_guides/custom_charts.md b/vizro-core/docs/pages/user_guides/custom_charts.md index ddb4392bf..cb7ca59dc 100644 --- a/vizro-core/docs/pages/user_guides/custom_charts.md +++ b/vizro-core/docs/pages/user_guides/custom_charts.md @@ -3,8 +3,14 @@ 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]. +The figures provided there work out of the box without having to create a custom chart. However, there are several use cases where you might want to create a custom chart. -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: +**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) + +In general, custom/customized charts need to obey the following conditions: !!! note "Conditions for using any `go.Figure()` in [`Graph`][vizro.models.Graph]" - a `go.Figure()` object is returned by a function From 81d7509379d665ccb79776cfebf999fdff675626 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 20:05:17 +0200 Subject: [PATCH 03/14] Add examples for custom components --- vizro-core/docs/pages/user_guides/custom_charts.md | 6 +++--- vizro-core/docs/pages/user_guides/custom_components.md | 9 +++++++-- 2 files changed, 10 insertions(+), 5 deletions(-) diff --git a/vizro-core/docs/pages/user_guides/custom_charts.md b/vizro-core/docs/pages/user_guides/custom_charts.md index cb7ca59dc..2b40c04e4 100644 --- a/vizro-core/docs/pages/user_guides/custom_charts.md +++ b/vizro-core/docs/pages/user_guides/custom_charts.md @@ -3,14 +3,14 @@ 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]. -The figures provided there work out of the box without having to create a custom chart. However, there are several use cases where you might want to create a custom chart. +In general, the usage of our custom chart decorator `@capture("graph")` is required if your plotly express chart requires any post-update calls or customization. -**When to use a custom chart?** +**When to use our custom chart decorator?** - 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) -In general, custom/customized charts need to obey the following conditions: +In general, custom charts need to obey the following conditions: !!! note "Conditions for using any `go.Figure()` in [`Graph`][vizro.models.Graph]" - a `go.Figure()` object is returned by a function diff --git a/vizro-core/docs/pages/user_guides/custom_components.md b/vizro-core/docs/pages/user_guides/custom_components.md index 0a40c68ab..47c901cc0 100644 --- a/vizro-core/docs/pages/user_guides/custom_components.md +++ b/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. 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. From cf5bdc922a871d2b2be9ba97f8e786c48d3e8892 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 20:46:11 +0200 Subject: [PATCH 04/14] Add more explanation for deployment --- vizro-core/docs/pages/user_guides/run.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/vizro-core/docs/pages/user_guides/run.md b/vizro-core/docs/pages/user_guides/run.md index bc6cdffb8..10cb791c8 100644 --- a/vizro-core/docs/pages/user_guides/run.md +++ b/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 functioning as a higher-level wrapper around Dash. 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() | From 8dec1c3bc7ae003f7b1630955bd04dfd93fbf7ef Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 21:00:59 +0200 Subject: [PATCH 05/14] Lint --- tools/check_branch_name.sh | 2 +- ...13_huong_li_nguyen_update_guides_custom.md | 42 +++++++++++++++++++ 2 files changed, 43 insertions(+), 1 deletion(-) create mode 100644 vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md diff --git a/tools/check_branch_name.sh b/tools/check_branch_name.sh index 7a9b067b1..0be2dd02a 100755 --- a/tools/check_branch_name.sh +++ b/tools/check_branch_name.sh @@ -1,7 +1,7 @@ #!/bin/sh BRANCH=$(git rev-parse --abbrev-ref HEAD) -REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci)\/[^/]+(/[^/]+)*)$" +REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci|tidy)\/[^/]+(/[^/]+)*)$" if ! [[ $BRANCH =~ $REGEX ]]; then diff --git a/vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md b/vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md new file mode 100644 index 000000000..d57e34cc2 --- /dev/null +++ b/vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md @@ -0,0 +1,42 @@ + + + + + + + + From edfa9512d8112affa5a312a70e8a4318a8f0c1fc Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 21:10:21 +0200 Subject: [PATCH 06/14] Lint --- vizro-core/docs/pages/user_guides/run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user_guides/run.md b/vizro-core/docs/pages/user_guides/run.md index 10cb791c8..e98675f0d 100644 --- a/vizro-core/docs/pages/user_guides/run.md +++ b/vizro-core/docs/pages/user_guides/run.md @@ -100,4 +100,4 @@ For reference (where app is a Dash app): |:-------------------------------|:--------------------------------| | Vizro() | app | | Vizro().build(dashboard) | app (after creating app.layout) | -| Vizro().build(dashboard).run() | app.run() | +| Vizro().build(dashboard).run() | app.run() | \ No newline at end of file From ee481c0ed2f64d98c47b93dbd297bcdd1881695c Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 21:52:43 +0200 Subject: [PATCH 07/14] Retrieve branch name differently --- tools/check_branch_name.sh | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/tools/check_branch_name.sh b/tools/check_branch_name.sh index 0be2dd02a..1b91e6c4e 100755 --- a/tools/check_branch_name.sh +++ b/tools/check_branch_name.sh @@ -1,6 +1,6 @@ #!/bin/sh -BRANCH=$(git rev-parse --abbrev-ref HEAD) +BRANCH=$(git name-rev --name-only HEAD) REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci|tidy)\/[^/]+(/[^/]+)*)$" From bdcbbe07d6a88d8dfc6c47b9790bd2bbcc8a7fce Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 22:07:08 +0200 Subject: [PATCH 08/14] Try out different git command --- tools/check_branch_name.sh | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/tools/check_branch_name.sh b/tools/check_branch_name.sh index 1b91e6c4e..abb1373c4 100755 --- a/tools/check_branch_name.sh +++ b/tools/check_branch_name.sh @@ -1,10 +1,9 @@ #!/bin/sh -BRANCH=$(git name-rev --name-only HEAD) +BRANCH=$(git symbolic-ref --short HEAD) REGEX="^(main|(release|feat|bug|docs|qa|dev|demo|ci|tidy)\/[^/]+(/[^/]+)*)$" - if ! [[ $BRANCH =~ $REGEX ]]; then - echo "Invalid branch name - please rename your branch following this $REGEX syntax." + echo "Branch name '$BRANCH' is invalid - please rename your branch following this regex syntax: $REGEX" exit 1 -fi +fi \ No newline at end of file From 4615262b5ceb69052c59e6eff64ae9a7c4c4ccd9 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 22:15:31 +0200 Subject: [PATCH 09/14] Try double condition due to different syntax --- tools/check_branch_name.sh | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/tools/check_branch_name.sh b/tools/check_branch_name.sh index abb1373c4..da7fcde30 100755 --- a/tools/check_branch_name.sh +++ b/tools/check_branch_name.sh @@ -1,9 +1,10 @@ #!/bin/sh -BRANCH=$(git symbolic-ref --short HEAD) +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 =~ $REGEX ]]; then - echo "Branch name '$BRANCH' is invalid - please rename your branch following this regex syntax: $REGEX" +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 \ No newline at end of file +fi From 6f13dac34bd0c2a61b62c8c69277bfd72e6b3b5e Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Thu, 12 Oct 2023 22:19:22 +0200 Subject: [PATCH 10/14] Lint --- vizro-core/docs/pages/user_guides/run.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user_guides/run.md b/vizro-core/docs/pages/user_guides/run.md index e98675f0d..10cb791c8 100644 --- a/vizro-core/docs/pages/user_guides/run.md +++ b/vizro-core/docs/pages/user_guides/run.md @@ -100,4 +100,4 @@ For reference (where app is a Dash app): |:-------------------------------|:--------------------------------| | Vizro() | app | | Vizro().build(dashboard) | app (after creating app.layout) | -| Vizro().build(dashboard).run() | app.run() | \ No newline at end of file +| Vizro().build(dashboard).run() | app.run() | From 8ca291eb218b4a2659500e9c6756bee7002bc6c8 Mon Sep 17 00:00:00 2001 From: Alexey Snigir Date: Fri, 13 Oct 2023 11:31:23 +0200 Subject: [PATCH 11/14] codespell fix --- pyproject.toml | 1 - tools/forbidden_words.txt | 1 - 2 files changed, 2 deletions(-) delete mode 100644 tools/forbidden_words.txt diff --git a/pyproject.toml b/pyproject.toml index 631dd2324..1f32312eb 100644 --- a/pyproject.toml +++ b/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] diff --git a/tools/forbidden_words.txt b/tools/forbidden_words.txt deleted file mode 100644 index af5101b91..000000000 --- a/tools/forbidden_words.txt +++ /dev/null @@ -1 +0,0 @@ -quantumblack->Please do not refer specific entities From 2e96c074a2bdc096156655c8c115e57e602541bc Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Fri, 13 Oct 2023 14:53:03 +0200 Subject: [PATCH 12/14] PR comments --- vizro-core/docs/pages/user_guides/custom_charts.md | 4 ++-- vizro-core/docs/pages/user_guides/custom_components.md | 2 +- vizro-core/docs/pages/user_guides/run.md | 2 +- 3 files changed, 4 insertions(+), 4 deletions(-) diff --git a/vizro-core/docs/pages/user_guides/custom_charts.md b/vizro-core/docs/pages/user_guides/custom_charts.md index 2b40c04e4..8f1a9cad7 100644 --- a/vizro-core/docs/pages/user_guides/custom_charts.md +++ b/vizro-core/docs/pages/user_guides/custom_charts.md @@ -3,9 +3,9 @@ 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]. -In general, the usage of our custom chart decorator `@capture("graph")` is required if your plotly express chart requires any post-update calls or customization. +In general, the usage of our custom chart decorator `@capture("graph")` is required if your plotly chart requires any post-update calls or customization. -**When to use our custom chart decorator?** +When to use our custom chart decorator - 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) diff --git a/vizro-core/docs/pages/user_guides/custom_components.md b/vizro-core/docs/pages/user_guides/custom_components.md index 47c901cc0..315c19484 100644 --- a/vizro-core/docs/pages/user_guides/custom_components.md +++ b/vizro-core/docs/pages/user_guides/custom_components.md @@ -8,7 +8,7 @@ In general, you can create a custom component based on any dash-compatible compo !!!warning - When creating your own custom components, you are responsible for the security of your component (e.g. setting HTML from code which might expose users to cross-site scripting). 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. diff --git a/vizro-core/docs/pages/user_guides/run.md b/vizro-core/docs/pages/user_guides/run.md index 10cb791c8..0e2c9a428 100644 --- a/vizro-core/docs/pages/user_guides/run.md +++ b/vizro-core/docs/pages/user_guides/run.md @@ -91,7 +91,7 @@ in the cmd. For more gunicorn configuration, please refer to [gunicorn docs](htt ## Deployment of Vizro app -In general, Vizro is functioning as a higher-level wrapper around Dash. So if you want to deploy a Vizro app, similar steps apply as if you were to deploy a Dash 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): From 9de84bd44be7068efa41dcea2ede7061bee861a5 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Fri, 13 Oct 2023 16:04:38 +0200 Subject: [PATCH 13/14] Improve titles --- .../docs/pages/user_guides/custom_charts.md | 21 ++++++++++--------- 1 file changed, 11 insertions(+), 10 deletions(-) diff --git a/vizro-core/docs/pages/user_guides/custom_charts.md b/vizro-core/docs/pages/user_guides/custom_charts.md index 8f1a9cad7..b00946daf 100644 --- a/vizro-core/docs/pages/user_guides/custom_charts.md +++ b/vizro-core/docs/pages/user_guides/custom_charts.md @@ -1,22 +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]. -In general, the usage of our custom chart decorator `@capture("graph")` is required if your plotly chart requires any post-update calls or customization. -When to use our custom chart decorator +## 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) -In general, custom charts need to obey the following conditions: +### 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. @@ -151,4 +152,4 @@ The below examples shows a more involved use-case. We create and style a waterfa === "Result" [![Graph3]][Graph3] - [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png + [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png \ No newline at end of file From 3fa15e1a13748764824261e37c520fd4b4a00569 Mon Sep 17 00:00:00 2001 From: huong-li-nguyen Date: Fri, 13 Oct 2023 16:08:21 +0200 Subject: [PATCH 14/14] Lint --- vizro-core/docs/pages/user_guides/custom_charts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/vizro-core/docs/pages/user_guides/custom_charts.md b/vizro-core/docs/pages/user_guides/custom_charts.md index b00946daf..337b6424b 100644 --- a/vizro-core/docs/pages/user_guides/custom_charts.md +++ b/vizro-core/docs/pages/user_guides/custom_charts.md @@ -152,4 +152,4 @@ The below examples shows a more involved use-case. We create and style a waterfa === "Result" [![Graph3]][Graph3] - [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png \ No newline at end of file + [Graph3]: ../../assets/user_guides/custom_charts/custom_chart_waterfall.png