plots: document html template by pared · Pull Request #2472 · treeverse/dvc.org

pared · 2021-05-13T14:04:06Z

You may disregard these recommendations if you used the Edit on GitHub button from dvc.org to improve a doc in place.

❗ Please read the guidelines in the Contributing to the Documentation list if you make any substantial changes to the documentation or JS engine.

🐛 Please make sure to mention Fix #issue (if applicable) in the description of the PR. This causes GitHub to close it automatically when the PR is merged.

Please choose to allow us to edit your branch when creating the PR.

Thank you for the contribution - we'll try to review it as soon as possible. 🙏

Fixes #2402
Closes #1175

jorgeorpinel

Fixing broken links (will commit, please git pull)

iesahin · 2021-05-25T20:58:05Z

I have edited the guide heavily and had minor edits in ref documents. Guide's title and filename are also changed. Please pull :)

Sidebar doesn't have a link for the document.

iesahin

The web server part seems a bit irrelevant, as it seems possible to link the JS files directly to the template. Browsers should be loading the src of <script> tags from local files if I'm not mistaken. The current guide leads the user to run the web server for their own local plots always.

I would like the web server part removed and template to have <script src="my-vega.js"/> elements instead.

iesahin · 2021-05-26T08:51:43Z

Sign in to view

+
+DVC allows to provide a custom HTML template to avoid this requirement.
+
+## Example: Setup local server with Vega libraries


Is it not possible to skip the web server part and embed the JavaScript files directly in the template with something like <script src="./vega.js"/>? @pared

This was my initial idea, but I like the server version more due to its robustness:
If we specify server, we are pretty sure the address won't change for the same network. In case of local path, we need to assure two things:

that template path is absolute path (dvc plots produces html's in cwd, so relative paths would require some special logic dedicated to resolving vega libs paths according to cwd)

that all users copying given repo will have the vega libs under the same path

Using local server, I intend to point user to a solution that would be viable for intranet and would work without every user having to put libs in same place, or modify the project each time they change the machine they work on.

The final plots document will always need the webserver running in this case, right?

For the intranets, I see your points. That's surely more robust but that configuration can be completely different, e.g., they may already have a central URL to put the files and we don't expect users to copy-paste this template to their workflow.

We just want to show how to supply a template and the user might be looking for a way to render their plots completely differently.

I don't have a strong opinion on this and will trust your judgment. If you see it's better this way, let's keep it. For me, although it has some extra parts, the guide satisfies the purpose of describing the templates. Thank you.

I agree that server approach is overkill for example purposes, and tries to direct user into "proper" direction. Maybe lets make an example for local path, and just add note on the bottom of the page why one should consider "static" URL to js?

Hey, I managed to modify the guide to use local files.

@iesahin I'm still seeing the web server section so not sure what the conclusion was here.

jorgeorpinel

OK I finally took a good look at this and there's lots of info here, which is great. Thanks for all the effort so far @pared and @iesahin ! Here's my high-level review:

TBH if the change is basically to address treeverse/dvc#5679 specifically (see #2402 (comment)), I think the changes are a bit too much. Instead of a whole guide we can probably do with a section or example in the params cmd ref index (https://dvc.org/doc/command-reference/plots). It needs updating anyway since it only mentions Vega templates now.

In summary, I think we should summarize the current guide (quite a bit) and put in the plots index instead, probably both as updates to the Templating sections and as an example.

Also @iesahin I think we have enough info, mind taking this over? 🙏

But @pared def try to keep in mind its better to merge than rebase in docs PRs to avoid force pushing stuff we commit directly from Git (e.g. typos -- we do this often). Thanks!

Co-authored-by: Restyled.io <commits@restyled.io>

jorgeorpinel

Getting there!

Also, should we wait for a decision on treeverse/dvc#5694 (review)? Cc @pared. Otherwise we should remove the awaiting-dvc-merge label.

Thanks.

jorgeorpinel · 2021-06-29T05:25:48Z

+## HTML templates
+
+By default, the plots generated by `dvc plots` require Internet access to load
+Vega JavaScript libraries. It's possible to supply a custom HTML file to the
+`--html-template` option of `dvc plot show` and `dvc plot diff` when the
+Internet access is not available.


I don't think we should present this as a solution for offline envs initially. E,g. you can also use this feature even when you're online. Let's move most of that motivation to the example instead please.

So what's a more general motivation for this section that explains the feature? Perhaps something like "The default plots use a plain HTML file which uses cloud Vega libraries." Plus maybe link to the official "Vega libs" location. Is it https://github.com/vega/vega/releases?

Another motivation may be to put some extra stuff to the plots, like a banner, title etc. But in general, I think people will understand if something works offline, it can also work online.

Yes but offline vs online is not the broadest use, right? Templates are about customization in general. Offline js imports just happens to be one thing you can customize.

jorgeorpinel · 2021-06-29T05:26:19Z

+> `--html-template` provides a custom HTML file to inject plots generated by
+> DVC.
+
+You can create an HTML file with `<script>` references to local Vega libraries.


Same. That's not the sole use of this feature.

Main motivation is generating plots without Internet access and (maybe) customizing them. References to local Vega libraries captures both. Without Vega, the user cannot produce plots.

I realize that was the original purpose of the PR but once implemented, it's just one application of HTML template customization, I think.

jorgeorpinel · 2021-06-29T05:27:02Z

+### Example for the HTML template
+
+Download the Vega libraries into the directory where you'll produce the


Should the title be more specific? Something about offline environments or without Internet access.

(And let's start with a quick motivation intro as mentioned earlier 🙂)

pared · 2021-06-29T11:07:18Z

@jorgeorpinel I think the decision is there:
treeverse/dvc#6221 (comment)
I think we can wait till it gets merged.

jorgeorpinel

Specific suggestions on HTML template example file.

jorgeorpinel

Copy edits to HTML templates (will commit)

Co-authored-by: Restyled.io <commits@restyled.io>

jorgeorpinel

Example copy edits (committing)

Co-authored-by: Restyled.io <commits@restyled.io>

Almost there...

jorgeorpinel

Last questions @iesahin please finalize and lmk for merge (feel free to merge if you can) 👍

jorgeorpinel · 2021-07-14T00:01:50Z

+There may be times when you need to produce plots without Internet access, or
+want to customize the plots output to put some extra content, like banners or
+extra text. DVC allows to replace the HTML file that contains the final plots.


Suggested change

There may be times when you need to produce plots without Internet access, or

want to customize the plots output to put some extra content, like banners or

extra text. DVC allows to replace the HTML file that contains the final plots.

There may be times when you need to produce plots without Internet access.

DVC allows to replace the HTML file that contains the final plots.

or want to customize the plots output to put some extra content, like banners or extra text

The example isn't about that. Maybe mention these other examples in the Description subsection? Will leave suggestion ⏳

I don't think we can enumerate all use cases of templates in the description? We implement one of the example ideas, the rest can be done in a similar way.

I wasn't suggesting to enumerate every single possible case. My point was that this "Offline HTML Template" example is not about extra HTML content so that sentence just seems unrelated. Could just be removed IMO

jorgeorpinel · 2021-07-14T00:04:02Z

+using the the `--html-template` option. This allows you to customize the
+container where DVC will inject plots it generates.


⌛ Extracted from the example:

Suggested change

using the the `--html-template` option. This allows you to customize the

container where DVC will inject plots it generates.

using the the `--html-template` option. This allows you to customize the

container where DVC will inject the plots it generates.

For example, you can add extra content to the web page, like banners or links.

shcheklein · 2021-07-16T00:27:01Z

Merging this to move forward :)

pared added 2 commits May 13, 2021 15:52

user guide: add custom plots html guide

fe3eb5b

plots/config: add entries for html_tempalte

7d4790c

shcheklein temporarily deployed to dvc-org-2402-document-h-8hmmms May 13, 2021 14:04 Inactive

This comment has been minimized.

Sign in to view

jorgeorpinel reviewed May 13, 2021

View reviewed changes

Comment thread content/docs/command-reference/config.md Outdated

Comment thread content/docs/command-reference/plots/diff.md Outdated

Comment thread content/docs/command-reference/plots/show.md Outdated

ref: fix broken links in plots

594e43d

jorgeorpinel temporarily deployed to dvc-org-2402-document-h-8hmmms May 13, 2021 18:15 Inactive

jorgeorpinel added the dvc-update label May 13, 2021

pared changed the title ~~plots: document html tempalte~~ plots: document html template May 14, 2021

This comment has been minimized.

Sign in to view

jorgeorpinel assigned iesahin May 20, 2021

iesahin added 2 commits May 25, 2021 23:54

Edited the guide for clarity

83c644a

Minor edits

537bcf3

link and filename update

88b56ce

This comment has been minimized.

Sign in to view

jorgeorpinel requested a review from iesahin May 26, 2021 04:21

jorgeorpinel unassigned iesahin May 26, 2021

iesahin previously requested changes May 27, 2021

View reviewed changes

pared self-assigned this May 28, 2021

pared force-pushed the 2402_document_html_template branch from 88b56ce to 9fdb8e3 Compare May 31, 2021 17:23

This comment has been minimized.

Sign in to view

pared force-pushed the 2402_document_html_template branch from 9fdb8e3 to 198aace Compare June 1, 2021 11:25

jorgeorpinel mentioned this pull request Jun 2, 2021

ref: Update dvc plots to include information about offline HTML plots #2402

Closed

jorgeorpinel reviewed Jun 2, 2021

View reviewed changes

jorgeorpinel assigned iesahin and jorgeorpinel and unassigned pared and jorgeorpinel Jun 2, 2021

restyled-io Bot mentioned this pull request Jun 29, 2021

Restyle plots: document html template #2588

Merged

Restyled by prettier (#2588)

e34219f

Co-authored-by: Restyled.io <commits@restyled.io>

jorgeorpinel previously requested changes Jun 29, 2021

View reviewed changes

jorgeorpinel temporarily deployed to dvc-org-2402-document-h-7rvxlx June 29, 2021 05:37 Inactive

minor changes after review

027e390

shcheklein temporarily deployed to dvc-org-2402-document-h-7rvxlx July 6, 2021 10:46 Inactive

jorgeorpinel removed the ⌛ status: wait-core-merge Waiting for related product PR merge/release label Jul 6, 2021

jorgeorpinel reviewed Jul 6, 2021

View reviewed changes

Comment thread content/docs/command-reference/plots/index.md Outdated

Comment thread content/docs/command-reference/plots/index.md Outdated

Comment thread content/docs/command-reference/plots/index.md Outdated

Modified description to be more general.

fd6ef99

shcheklein temporarily deployed to dvc-org-2402-document-h-7rvxlx July 13, 2021 18:26 Inactive

jorgeorpinel reviewed Jul 13, 2021

View reviewed changes

Comment thread content/docs/command-reference/plots/index.md Outdated

Comment thread content/docs/command-reference/plots/index.md Outdated

Comment thread content/docs/command-reference/plots/index.md Outdated

Comment thread content/docs/command-reference/plots/index.md Outdated

ref: copy edits to plots HTML templates

7cc1a56

jorgeorpinel temporarily deployed to dvc-org-2402-document-h-7rvxlx July 13, 2021 23:44 Inactive

restyled-io Bot mentioned this pull request Jul 13, 2021

Restyle plots: document html template #2629

Merged

Restyled by prettier (#2629)

4c82136

Co-authored-by: Restyled.io <commits@restyled.io>

jorgeorpinel temporarily deployed to dvc-org-2402-document-h-7rvxlx July 13, 2021 23:45 Inactive

jorgeorpinel reviewed Jul 13, 2021

View reviewed changes

ref: copy edits to plots HTML template example

4e854a5

jorgeorpinel temporarily deployed to dvc-org-2402-document-h-7rvxlx July 13, 2021 23:58 Inactive

restyled-io Bot mentioned this pull request Jul 13, 2021

Restyle plots: document html template #2630

Merged

Restyled by prettier (#2630)

741dc75

Co-authored-by: Restyled.io <commits@restyled.io>

jorgeorpinel temporarily deployed to dvc-org-2402-document-h-7rvxlx July 13, 2021 23:59 Inactive

jorgeorpinel approved these changes Jul 14, 2021

View reviewed changes

minor modifications in filenames

f75ba9a

shcheklein temporarily deployed to dvc-org-2402-document-h-7rvxlx July 14, 2021 12:17 Inactive

shcheklein merged commit 63e0c00 into master Jul 16, 2021

shcheklein deleted the 2402_document_html_template branch July 23, 2021 18:58


		DVC allows to provide a custom HTML template to avoid this requirement.

		## Example: Setup local server with Vega libraries

		### Example for the HTML template

		Download the Vega libraries into the directory where you'll produce the

		using the the `--html-template` option. This allows you to customize the
		container where DVC will inject plots it generates.

Conversation

pared commented May 13, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

This comment has been minimized.

jorgeorpinel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

This comment has been minimized.

iesahin commented May 25, 2021

Uh oh!

This comment has been minimized.

iesahin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pared May 27, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment was marked as resolved.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

This comment has been minimized.

This comment has been minimized.

jorgeorpinel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorgeorpinel left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorgeorpinel Jun 29, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorgeorpinel Jul 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

jorgeorpinel Jul 6, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pared commented Jun 29, 2021

Uh oh!

jorgeorpinel left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

pared commented May 13, 2021 •

edited

Loading

pared May 27, 2021 •

edited

Loading

jorgeorpinel left a comment •

edited

Loading

jorgeorpinel left a comment •

edited

Loading

jorgeorpinel Jun 29, 2021 •

edited

Loading

jorgeorpinel Jul 6, 2021 •

edited

Loading

jorgeorpinel Jul 6, 2021 •

edited

Loading

jorgeorpinel left a comment •

edited

Loading