plots: document html template (#2472)

* user guide: add custom plots html guide * plots/config: add entries for html_tempalte * ref: fix broken links in plots * Edited the guide for clarity * Minor edits * link and filename update * modified for non-http-server introduction * moved the information to `/doc/command-reference/plots/` * moved the example to the bottom. some minor fixes. * minor changes in the example * removed the ug document * ref: copy edits to HTML plot templates info. * Restyled by prettier (#2588) Co-authored-by: Restyled.io <[email protected]> * minor changes after review * Modified description to be more general. * ref: copy edits to plots HTML templates * Restyled by prettier (#2629) Co-authored-by: Restyled.io <[email protected]> * ref: copy edits to plots HTML template example * Restyled by prettier (#2630) Co-authored-by: Restyled.io <[email protected]> * minor modifications in filenames Co-authored-by: Jorge Orpinel <[email protected]> Co-authored-by: Emre Sahin <[email protected]> Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com> Co-authored-by: Restyled.io <[email protected]>
iterative · Jul 16, 2021 · 63e0c00 · 63e0c00
1 parent e0bd5a7
commit 63e0c00
Show file tree

Hide file tree

Showing 4 changed files with 78 additions and 2 deletions.
diff --git a/content/docs/command-reference/config.md b/content/docs/command-reference/config.md
@@ -239,6 +239,12 @@ to learn more about the state file (database) that is used for optimization.
   updates the timestamp on that entry. This way, when the database needs a
   cleanup, DVC can sort entries chronologically, and remove the oldest ones.
 
+### plots
+
+- `plots.html_template` - sets a
+  [custom HTML template](/doc/command-reference/plots#html-templates) for
+  `dvc plots`. Accepts a path relative to the `.dvc/` folder.
+
 ## Example: Add an S3 remote, and set it as default
 
 > 💡 Before adding an S3 remote, be sure to

diff --git a/content/docs/command-reference/plots/diff.md b/content/docs/command-reference/plots/diff.md
@@ -11,7 +11,7 @@ usage: dvc plots diff [-h] [-q | -v]
                       [-t <name_or_path>] [-x <field>] [-y <field>]
                       [--no-header] [--title <text>]
                       [--x-label <text>] [--y-label <text>] [-o <path>]
-                      [--show-vega] [--open]
+                      [--show-vega] [--open] [--html-template <path>]
                       [revisions [revisions ...]]
 
 positional arguments:
@@ -97,6 +97,9 @@ all the current plots, without comparisons.
   header. A 0-based numeric index can be used to identify each column instead of
   names.
 
+- `--html-template <path>` - path to a
+  [custom HTML template](/doc/command-reference/plots#html-templates).
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

diff --git a/content/docs/command-reference/plots/index.md b/content/docs/command-reference/plots/index.md
@@ -158,6 +158,20 @@ header (first row) are equivalent to field names.
 
 - `<DVC_METRIC_Y_LABEL>` (optional) - field name to display as the X axis label
 
+## HTML templates
+
+It's possible to supply an HTML file to `dvc plot show` and `dvc plot diff` by
+using the the `--html-template` option. This allows you to customize the
+container where DVC will inject plots it generates.
+
+> ⚠️ This is a separate feature from
+> [custom Vega templates](/doc/command-reference/plots#custom-templates).
+
+The only requirement for this HTML file is to specify the place to inject plots
+with a `{plot_divs}` marker. See an
+[example](/doc/command-reference/plots#example-offline-html-template) that uses
+this feature to render DVC plots without an Internet connection, below.
+
 ## Options
 
 - `-h`, `--help` - prints the usage/help message, and exit.
@@ -260,3 +274,53 @@ file:///Users/usr/src/plots/classes.csv.html
 
 > A confusion matrix [template](/doc/command-reference/plots#plot-templates) is
 > predefined in DVC (found in `.dvc/plots/confusion.json`).
+
+### Example: Offline HTML Template
+
+The plots generated by `dvc plots` uses Vega JavaScript libraries, and by
+default these load [online resources](https://vega.github.io/vega/usage/#embed).
+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.
+
+Download the Vega libraries into the directory where you'll produce the
+`dvc plots`:
+
+```dvc
+$ wget https://cdn.jsdelivr.net/npm/[email protected] -O my_vega.js
+$ wget https://cdn.jsdelivr.net/npm/[email protected] -O my_vega_lite.js
+$ wget https://cdn.jsdelivr.net/npm/[email protected] -O my_vega_embed.js
+```
+
+Create the following HTML file and save it in `.dvc/plots/mypage.html`:
+
+```html
+<html>
+  <head>
+    <script src="my_vega.js" type="text/javascript"></script>
+    <script src="my_vega_lite.js" type="text/javascript"></script>
+    <script src="my_vega_embed.js" type="text/javascript"></script>
+  </head>
+  <body>
+    {plot_divs}
+  </body>
+</html>
+```
+
+Note that this is a standard HTML file with only `{plot_divs}` as a placeholder
+for DVC to inject plots. `<script>` tags in this file point to the local
+JavaScript libraries we downloaded above. We can use it like this:
+
+```dvc
+$ dvc plots show --html-template .dvc/plots/mypage.html
+```
+
+You can also make it the default HTML template by setting it as `dvc config`
+parameter `plots.html_template`.
+
+```dvc
+$ dvc config plots.html_template plots/mypage.html
+```
+
+Note that the path supplied to `dvc config plots.html_template` is relative to
+`.dvc/` directory.
diff --git a/content/docs/command-reference/plots/show.md b/content/docs/command-reference/plots/show.md
@@ -8,7 +8,7 @@ Generate [plot](/doc/command-reference/plots) from a metrics file.
 usage: dvc plots show [-h] [-q | -v] [-t <name_or_path>] [-x <field>]
                       [-y <field>] [--no-header] [--title <text>]
                       [--x-label <text>] [--y-label <text>] [-o <path>]
-                      [--show-vega] [--open]
+                      [--show-vega] [--open] [--html-template <path>]
                       [targets [targets ...]]
 
 positional arguments:
@@ -70,6 +70,9 @@ please see `dvc plots`.
 - `--no-header` - lets DVC know that CSV or TSV `targets` do not have a header.
   A 0-based numeric index can be used to identify each column instead of names.
 
+- `--html-template <path>` - path to a
+  [custom HTML template](/doc/command-reference/plots#html-templates).
+
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no