From b773153e1d97d03ba9c580e4bf28bc0077f97eff Mon Sep 17 00:00:00 2001 From: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Date: Fri, 13 Oct 2023 16:21:34 +0200 Subject: [PATCH] Update user guides and implement branch name prefix enforcement (#110) Co-authored-by: Alexey Snigir --- .pre-commit-config.yaml | 5 +++ pyproject.toml | 1 - tools/check_branch_name.sh | 10 +++++ tools/forbidden_words.txt | 1 - ...13_huong_li_nguyen_update_guides_custom.md | 42 +++++++++++++++++++ .../docs/pages/user_guides/custom_charts.md | 21 ++++++---- .../pages/user_guides/custom_components.md | 9 +++- vizro-core/docs/pages/user_guides/run.md | 13 ++++++ 8 files changed, 91 insertions(+), 11 deletions(-) create mode 100755 tools/check_branch_name.sh delete mode 100644 tools/forbidden_words.txt create mode 100644 vizro-core/changelog.d/20231012_205313_huong_li_nguyen_update_guides_custom.md diff --git a/.pre-commit-config.yaml b/.pre-commit-config.yaml index 4cd228c4b..df8064356 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.6 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/check_branch_name.sh b/tools/check_branch_name.sh new file mode 100755 index 000000000..da7fcde30 --- /dev/null +++ b/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 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 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 @@ + + + + + + + + diff --git a/vizro-core/docs/pages/user_guides/custom_charts.md b/vizro-core/docs/pages/user_guides/custom_charts.md index ddb4392bf..337b6424b 100644 --- a/vizro-core/docs/pages/user_guides/custom_charts.md +++ b/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. diff --git a/vizro-core/docs/pages/user_guides/custom_components.md b/vizro-core/docs/pages/user_guides/custom_components.md index 0a40c68ab..315c19484 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. 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 bc6cdffb8..0e2c9a428 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 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() |