From 88328e1b87d5cf566308555f4bc539f2aea2fd62 Mon Sep 17 00:00:00 2001 From: AnnMarueW Date: Mon, 1 Jan 2024 20:41:08 -0800 Subject: [PATCH 1/4] update docs for meta tags feature --- .../docs/pages/development/contributing.md | 11 +++++++++- vizro-core/docs/pages/user_guides/assets.md | 21 ++++++++++++++----- .../docs/pages/user_guides/dashboard.md | 15 ++++++++++--- vizro-core/docs/pages/user_guides/pages.md | 3 +++ 4 files changed, 41 insertions(+), 9 deletions(-) diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md index bc4b9c517..9532fe05d 100644 --- a/vizro-core/docs/pages/development/contributing.md +++ b/vizro-core/docs/pages/development/contributing.md @@ -44,6 +44,14 @@ hatch run example from_dict If no example is specified (`hatch run example`) then the [default example](https://github.com/mckinsey/vizro/tree/main/vizro-core/examples/default/app.py) is used. +## Documentation + + If you're modifying documentation, the following will do a hot-reloading build of the rendered docs: + +```console +hatch run docs:serve +``` + ## Debugging tips - [Dash dev tools](https://dash.plotly.com/devtools) are enabled in all the Hatch environments by setting environment variable `DASH_DEBUG = "true"`, and so there is no need to specify `debug=True` when calling `Vizro.run` to enable them. The reload functionality, callback graph and in-browser error messages are particularly useful. @@ -124,7 +132,7 @@ Note that Hatch's `default` environment specifies `pre-commit` as a dependency b We use [gitleaks](https://github.com/gitleaks/gitleaks) for secret scanning. We do this via `pre-commit`, however there are a few things to note: -1. Using `gitleaks` may require an installation of `go` on the developer machine. This is easy and explained [here](https://go.dev/doc/install). +1. Using `gitleaks` may require an installation of `go` on the developer machine. This is easy and explained in the [Go documentation](https://go.dev/doc/install). 2. For that reason `hatch run lint` skips the secret scans, to function on all machines. 3. To run a secret-scan, simply run `hatch run secrets`. 4. Secret scans will run on CI, but it is highly recommended to check for secrets **before pushing to the remote repository** and ideally also before even committing. @@ -146,6 +154,7 @@ Note that `requirements.txt` is not used by Hatch, and so it should not be edite manually for dependency management. Instead, edit `pyproject.toml` or `hatch.toml` when adding or removing dependencies. +## ## Changelog Vizro keeps a changelog, where all notable changes to the project will be documented. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), diff --git a/vizro-core/docs/pages/user_guides/assets.md b/vizro-core/docs/pages/user_guides/assets.md index dced19937..df2ec19b1 100644 --- a/vizro-core/docs/pages/user_guides/assets.md +++ b/vizro-core/docs/pages/user_guides/assets.md @@ -15,16 +15,17 @@ The user-provided `assets` folder thus always takes precedence. │  ├── images │  ├── icons │  ├── collections.svg -├── favicon.ico +│  ├── app.svg +│  ├── favicon.ico ``` ## 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. -For more information, see [here](https://dash.plotly.com/external-resources#changing-the-favicon). +For more information, see the [Dash documentation](https://dash.plotly.com/external-resources#changing-the-favicon). ## Overwriting global CSS properties To overwrite any global CSS properties of existing components, target the right CSS property and place your CSS files in the `assets` folder. This will overwrite any existing defaults for that CSS property. -For reference, all Vizro CSS files can be found [here](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css). +For reference, see the [Vizro CSS files](https://github.com/mckinsey/vizro/tree/main/vizro-core/src/vizro/static/css). !!! example "Customizing global CSS properties" === "my_css_file.css" @@ -82,7 +83,7 @@ For reference, all Vizro CSS files can be found [here](https://github.com/mckins ## Overwriting CSS properties in selective components To overwrite CSS properties of selective components, provide an ID to the relevant component and target the right CSS property. -For more information on how CSS selectors work, see [here](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure). +For more information, see this [CSS selectors tutorial](https://developer.mozilla.org/en-US/docs/Web/CSS/CSS_selectors/Selector_structure). Let's say we want to change the background and font-color of one [`Card`][vizro.models.Card] instead of all existing Cards in the Dashboard. We can use the ID of the outermost Div to target the inner sub-components of the card. Note that all our components have an ID attached to the outermost Div, @@ -169,4 +170,14 @@ app = Vizro(assets_folder="path/to/assets/folder").build(dashboard).run() ``` Note that in the example above, you still need to configure your [`Page`][vizro.models.Page]. -A guide on how to do that you can find [here](pages.md). +See more information in the [Pages User Guide](pages.md). + + +## Meta tags image + +Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat +clients. To include an image in the preview, place an image file in the assets folder named `app.` or +`logo.`. Vizro searches the assets folder and uses the first one it finds. + +Image types of `apng`, `avif`, `gif`, `jpeg`, `jpg`, `png`, `svg`, and `webp` are supported. + diff --git a/vizro-core/docs/pages/user_guides/dashboard.md b/vizro-core/docs/pages/user_guides/dashboard.md index 363ae63de..0659f91c5 100644 --- a/vizro-core/docs/pages/user_guides/dashboard.md +++ b/vizro-core/docs/pages/user_guides/dashboard.md @@ -191,7 +191,16 @@ After running the dashboard, you can access the dashboard via `localhost:8050`. ## Adding a dashboard title -If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top left of every page. It is also combined with the `title` specified in [`Page`][vizro.models.Page] to set: +If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top left of every page. -- `` HTML element that controls the text labeling a browser window; -- `<meta>` elements that control how a preview is generated when sharing a link to your dashboard (e.g. on social media). + +## Browser title + +The [website icon](assets.md/#changing-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's +title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage". + +## Meta tags for social media + +Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat +clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#meta-tags-image) and +[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing the [Vizro demo app](https://vizro.mckinsey.com/). diff --git a/vizro-core/docs/pages/user_guides/pages.md b/vizro-core/docs/pages/user_guides/pages.md index e733b7f32..06dcec12e 100644 --- a/vizro-core/docs/pages/user_guides/pages.md +++ b/vizro-core/docs/pages/user_guides/pages.md @@ -25,6 +25,7 @@ To create and add a page to your dashboard, do the following steps: 2. Configure your `components`, see our guide on [Charts/Components](components.md) 3. (optional) Configure your `controls` , see our guides on [Filters](filters.md) and [Parameters](parameters.md) 4. (optional) Configure your `layout` , see our guide on [Layouts](layouts.md) +5. (optional) Provide a `description` of your `Page` for the app's [meta tags](https://metatags.io/) !!! example "Page" === "app.py" @@ -37,6 +38,7 @@ To create and add a page to your dashboard, do the following steps: page = vm.Page( title="Page Title", + description="Longer description of the page content", components=[ vm.Graph( id="sunburst", figure=px.sunburst(gapminder, path=["continent", "country"], values="pop", color="lifeExp") @@ -79,6 +81,7 @@ To create and add a page to your dashboard, do the following steps: - sunburst.color type: parameter title: Page Title + description: "Longer description of the page content" ``` === "Result" [![Page]][Page] From c363c003079a9566cf9b8ed4d714c7a49e7bfaed Mon Sep 17 00:00:00 2001 From: "pre-commit-ci[bot]" <66853113+pre-commit-ci[bot]@users.noreply.github.com> Date: Tue, 2 Jan 2024 04:53:45 +0000 Subject: [PATCH 2/4] [pre-commit.ci] auto fixes from pre-commit.com hooks for more information, see https://pre-commit.ci --- vizro-core/docs/pages/development/contributing.md | 7 ++++--- vizro-core/docs/pages/user_guides/assets.md | 9 ++++----- vizro-core/docs/pages/user_guides/dashboard.md | 8 ++++---- 3 files changed, 12 insertions(+), 12 deletions(-) diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md index 9532fe05d..bb55ef622 100644 --- a/vizro-core/docs/pages/development/contributing.md +++ b/vizro-core/docs/pages/development/contributing.md @@ -46,8 +46,8 @@ If no example is specified (`hatch run example`) then the [default example](http ## Documentation - If you're modifying documentation, the following will do a hot-reloading build of the rendered docs: - +If you're modifying documentation, the following will do a hot-reloading build of the rendered docs: + ```console hatch run docs:serve ``` @@ -154,7 +154,8 @@ Note that `requirements.txt` is not used by Hatch, and so it should not be edite manually for dependency management. Instead, edit `pyproject.toml` or `hatch.toml` when adding or removing dependencies. -## +## + ## Changelog Vizro keeps a changelog, where all notable changes to the project will be documented. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), diff --git a/vizro-core/docs/pages/user_guides/assets.md b/vizro-core/docs/pages/user_guides/assets.md index df2ec19b1..f6383686a 100644 --- a/vizro-core/docs/pages/user_guides/assets.md +++ b/vizro-core/docs/pages/user_guides/assets.md @@ -15,7 +15,7 @@ The user-provided `assets` folder thus always takes precedence. │  ├── images │  ├── icons │  ├── collections.svg -│  ├── app.svg +│  ├── app.svg │  ├── favicon.ico ``` @@ -175,9 +175,8 @@ See more information in the [Pages User Guide](pages.md). ## Meta tags image -Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat -clients. To include an image in the preview, place an image file in the assets folder named `app.<extension>` or -`logo.<extension>`. Vizro searches the assets folder and uses the first one it finds. +Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat +clients. To include an image in the preview, place an image file in the assets folder named `app.<extension>` or +`logo.<extension>`. Vizro searches the assets folder and uses the first one it finds. Image types of `apng`, `avif`, `gif`, `jpeg`, `jpg`, `png`, `svg`, and `webp` are supported. - diff --git a/vizro-core/docs/pages/user_guides/dashboard.md b/vizro-core/docs/pages/user_guides/dashboard.md index 0659f91c5..34ad46afe 100644 --- a/vizro-core/docs/pages/user_guides/dashboard.md +++ b/vizro-core/docs/pages/user_guides/dashboard.md @@ -191,16 +191,16 @@ After running the dashboard, you can access the dashboard via `localhost:8050`. ## Adding a dashboard title -If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top left of every page. +If supplied, the `title` of the [`Dashboard`][vizro.models.Dashboard] displays a heading at the top left of every page. ## Browser title -The [website icon](assets.md/#changing-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's +The [website icon](assets.md/#changing-the-favicon), Dashboard `title` (if supplied) and [Page `title`][vizro.models.Page] are displayed in the browser's title bar. For example, if your Dashboard `title` is "Vizro Demo" and the Page `title` is "Homepage", then the title in the browser tab will be "Vizro Demo: Homepage". ## Meta tags for social media -Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat +Vizro automatically adds [meta tags](https://metatags.io/) to display a preview card when your app is shared on social media and chat clients. The preview includes the `URL`, `title`, plus an [image](assets.md/#meta-tags-image) and -[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing the [Vizro demo app](https://vizro.mckinsey.com/). +[Page `description`][vizro.models.Page] (if supplied). To see an example, try sharing the [Vizro demo app](https://vizro.mckinsey.com/). From f001371af0d8723bd5ae7650e66fca7eda565e4b Mon Sep 17 00:00:00 2001 From: Ann Marie Ward <72614349+AnnMarieW@users.noreply.github.com> Date: Tue, 2 Jan 2024 06:45:24 -0800 Subject: [PATCH 3/4] Update vizro-core/docs/pages/development/contributing.md Co-authored-by: Li Nguyen <90609403+huong-li-nguyen@users.noreply.github.com> Signed-off-by: Ann Marie Ward <72614349+AnnMarieW@users.noreply.github.com> --- vizro-core/docs/pages/development/contributing.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/vizro-core/docs/pages/development/contributing.md b/vizro-core/docs/pages/development/contributing.md index bb55ef622..c5f4b0635 100644 --- a/vizro-core/docs/pages/development/contributing.md +++ b/vizro-core/docs/pages/development/contributing.md @@ -154,8 +154,6 @@ Note that `requirements.txt` is not used by Hatch, and so it should not be edite manually for dependency management. Instead, edit `pyproject.toml` or `hatch.toml` when adding or removing dependencies. -## - ## Changelog Vizro keeps a changelog, where all notable changes to the project will be documented. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), From 110d4dcfbb17297c72cf1a5c888f5bfd2226b942 Mon Sep 17 00:00:00 2001 From: AnnMarueW <amward@fastmail.com> Date: Tue, 2 Jan 2024 06:47:26 -0800 Subject: [PATCH 4/4] changelog --- ...102_064659_amward_update_docs_meta_tags.md | 48 +++++++++++++++++++ 1 file changed, 48 insertions(+) create mode 100644 vizro-core/changelog.d/20240102_064659_amward_update_docs_meta_tags.md diff --git a/vizro-core/changelog.d/20240102_064659_amward_update_docs_meta_tags.md b/vizro-core/changelog.d/20240102_064659_amward_update_docs_meta_tags.md new file mode 100644 index 000000000..f1f65e73c --- /dev/null +++ b/vizro-core/changelog.d/20240102_064659_amward_update_docs_meta_tags.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)) + +-->