Make plot templates optional

[aCampello]

This is for discussion.

Not all of us use plots when using dvc, so for many repositories when you do dvc init it will add a folder .dvc/plots with a lot of json files that end up being unused. It would be good to have an option to ignore these files, say

dvc init --no-plots

Then if the user don't have it and tries to do anything with dvc plot we create these templates (or perhaps throw an error saying they have to initialise a template).

[pared]

Related to #6513

[dberenbaum]

From #6550:

@pared:

Since we are changing the default template, the repositories created before this change would not be affected by this change. In order to prevent that we remove dumping plots templates on dvc init and make dvc try to match template by name (same as we do in the case of non-dvc repositories).

One drawback is that users lose the ability to edit default templates, as well as producing their own templates is harder since default ones are not simply under .dvc/plots. We could fix that by improving our docs with the "Create your custom template" example in plots documentation.

@dberenbaum:

To my understanding, current issues are:

• Templates may be out of date relative to dvc version.
• Including in .dvc/plots makes it easier for users to understand and create custom templates.
• Including the templates creates a lot of unnecessary additional files for many users.

So I propose:

Include only simple.json (or maybe call it example.json) in .dvc/plots (and get rid of the Python class for this template altogether).
Read the contents of the other included templates directly from the json files (so that we can still link to those for docs and users can copy them), but bundle those files with the package instead of the repo.

By the way, can templates be in $HOME/.config/dvc/plots for reuse across projects?

Interested to hear what you and others think.

@skshetry Do you think this makes sense for stage templates in dvc exp init?

@shcheklein Do you see any impacts for other products?

@shcheklein:

It might affect a bit other products. It should be fine with Studio (since it's Python), it might not be as fine for VS Code. We might need an interface to access templates in some way (e.g. to determine if that template merges data or not). I think it's doable even if dvc returns fully baked Vega JS in such cases, but it might be less efficient.

I think the point here is that by hiding them in the package we are indeed increasing complexity of people accessing them (manually, programmatically), so I would weight the benefits one more time to be honest. Not an obvious thing to do.

[dberenbaum]

It's not obvious to me that it's a downgrade in usability, especially since the package JSON files would be available in Github. If I were new to DVC, there's no way for me to see DVC templates now until I create a repo. Looking at the template doc in https://dvc.org/doc/command-reference/plots#plot-templates, I think it could be simplified and easier to grasp if it linked to the Github references for those template JSON files.

I also find the current implementation a little confusing. What's the difference between built-in templates and custom templates? Am I supposed to edit the templates in place or copy them and tweak them? I would be worried to edit them directly for fear that I would mess up the built-in templates. And as @pared mentioned in the linked PR, it's unclear how to get updated templates for my existing repo (why does my plot not have the interactive hover shown in the example docs even though I have the latest dvc version?).

Finally, users who aren't interested in custom plots dislike the unnecessary JSON files, which is a very minor inconvenience, but one that applies to the vast majority of users. To me, it's a bit like if dvc init added a shell config for every remote type in .dvc/config.

None of this is to say that the proposed changes are a definite improvement, but I see enough flaws in the current implementation that I want to make sure we aren't anchoring too much to the status quo.

[pared]

What's the difference between built-in templates and custom templates?

Not much - main difference is that if we put some template under .dvc/plots we are able to access them via their filename, without providing .json exceptions (when running dvc plots ... --template xyz) if there is no xyz template in current dir, we will look for xyz.json in .dvc/plots.

Am I supposed to edit the templates in place or copy them and tweak them?

One can edit them in place as well as copy and modify to own needs.

[dberenbaum]

Thanks, @pared! While I have looked at the plots enough to understand, I don't think the answers are obvious to a typical user.

[karajan1001]

Why can't we make .dvc/plots/ generated at dvc plot's first running

[dberenbaum]

Good point @karajan1001! We can do that, although I don't think it solves all issues like templates getting out of sync with DVC version.

[pared]

I don't think the answers are obvious to a typical user.

I can agree on that.

Why can't we make .dvc/plots/ generated at dvc plot's first running

We can but the problem will remain: the plots initialized once stay the same. So later development or changes like #6550 will have no effect on existing repositories, which creates quite a strange setup for users, where they have the newest dvc, yet the results it produces depends on their installation version.

[pmrowla]

What about bundling the default templates in the dvc package directory (so including them in MANIFEST.in and package_data in setup.py) instead of populating .dvc/plots/ with the defaults?

So by default when .dvc/plots/<template_name>.html doesn't exist we would look for it in pkg_resources.resource_filename('dvc.plots', 'templates/<template_name>.html').

If users want to override the defaults they can continue to do so in .dvc/plots/... (and we should provide some init command or flag to copy the current defaults into .dvc/plots for users to start with).

For users that are not using their own custom plots, they would just have an empty/nonexistent .dvc/plots/ dir and always get the latest default template (via whatever DVC release they are using) and users that are using their own customized versions would just continue to use their custom one instead of the latest default. (In the case for users customizing their own templates, they would be responsible for keeping them up to date with DVC releases as needed)

---

If we do it this way we could also just allow users to specify their own plots directory entirely (and search for matching templates in [custom_dir, .dvc/plots, DVC_PKG_DIR/plots/templates] with some documented priority) so that they can more easily use some shared set of plot templates between projects as needed

[pmrowla]

One thing to note is that users with existing repos would lose this auto-updated default plots behavior (since existing repos will already have a populated .dvc/plots dir)

[pared]

I think that depends on the implementation: if no template is provided, go for package data linear template.

[dberenbaum]

If we do it this way we could also just allow users to specify their own plots directory entirely (and search for matching templates in [custom_dir, .dvc/plots, DVC_PKG_DIR/plots/templates] with some documented priority) so that they can more easily use some shared set of plot templates between projects as needed

👍 I think this whole comment pretty well summarizes what we all have been discussing.

I think @pared also suggested the possibility of removing .dvc/plots entirely. The only downside I see to this is that it might be nice to provide a simple template example bundled with the repo somewhere. Is there other value in .dvc/plots?