DVCLive User Guide updates (#2814)

* Updated top-level index. Refactored user-guide to top level * Updated links * Added dvclive-html.gif * Explicit mention to automatic html update
iterative · Sep 9, 2021 · 562d37c · 562d37c
1 parent 2f83a5b
commit 562d37c
Show file tree

Hide file tree

Showing 17 changed files with 115 additions and 121 deletions.
diff --git a/...cs/dvclive/user-guide/dvclive-with-dvc.md → content/docs/dvclive/dvclive-with-dvc.md b/...cs/dvclive/user-guide/dvclive-with-dvc.md → content/docs/dvclive/dvclive-with-dvc.md
@@ -62,7 +62,7 @@ command options for the DVC integration:
 - `--live-no-cache <path>` - specify a DVCLive log directory `path` but don't
   tracked it with DVC. Useful if you prefer to track it with Git.
 - `--live-no-summary` - deactivates
-  [summary](/doc/dvclive/user-guide/quickstart#metrics-summary) generation.
+  [summary](/doc/dvclive/get-started#metrics-summary) generation.
 - `--live-no-html` - deactivates [HTML report](#html-report) generation.
 
 > Note that these are convenience CLI options. You can still use
@@ -105,13 +105,13 @@ experiments using DVCLive in DVC Studio.
 ### HTML report
 
 In addition to the
-[outputs described in the Quickstart](/doc/dvclive/user-guide/quickstart#outputs),
-DVC generates an _HTML report_.
+[outputs described in the Quickstart](/doc/dvclive/get-started#outputs), DVC
+generates an _HTML report_.
 
 If you open `training_metrics_dvc_plots/index.html` in a browser, you'll see a
-plot for metrics being logged during the model training!
+plot for metrics automatically updated during the model training!
 
-![](/img/dvclive-html-report.png)
+![](/img/dvclive-html.gif)
 
 ### Checkpoints
 

diff --git a/...ent/docs/dvclive/user-guide/quickstart.md → content/docs/dvclive/get-started.md b/...ent/docs/dvclive/user-guide/quickstart.md → content/docs/dvclive/get-started.md
@@ -1,4 +1,4 @@
-# Quickstart
+# Get Started
 
 DVCLive is a simple Python library whose interface consists of three main
 methods.
@@ -96,5 +96,5 @@ $ cat dvclive.json
 
 There are other ways to use DVCLive:
 
-- [DVCLive with DVC](/docs/dvclive/user-guide/dvclive-with-dvc)
-- [DVCLive with _ML Frameworks_](/docs/dvclive/user-guide/ml-frameworks/)
+- [DVCLive with DVC](/docs/dvclive/dvclive-with-dvc)
+- [DVCLive with _ML Frameworks_](/docs/dvclive/ml-frameworks)
diff --git a/content/docs/dvclive/index.md b/content/docs/dvclive/index.md
@@ -1,28 +1,36 @@
-# DVCLive
+# DVCLive Documentation
 
-[`DVCLive`](https://github.com/iterative/dvclive) is an open-source Python
-library for monitoring the progress of metrics during training of machine
-learning models. You can simply
+[DVCLive](https://github.com/iterative/dvclive) is an open-source Python library
+for monitoring the progress of metrics during training of machine learning
+models. You can simply
 [install it](https://github.com/iterative/dvclive#installation) with `pip`.
 
-DVCLive integrates seamlessly with `DVC` and the logs/summaries it produces can
-be fed as `dvc plots`/`dvc metrics`.
+<cards>
 
-However, `DVC` is not needed to work with DVCLive logs/summaries, and since
-they're saved as easily parsable TSV/JSON files, you can use your preferred
-visualization method.
+  <card href="/doc/dvclive/get-started" heading="Get Started">
+    A step-by-step introduction into basic DVCLive features
+  </card>
 
-We have created DVCLive with Git and MLOps principles in mind:
+  <card href="/doc/dvclive/dvclive-with-dvc" heading="DVCLive with DVC">
+    Discover how DVCLive and DVC can integrate in several useful ways
+  </card>
 
-- **Codification of data**. Tracked metrics are stored in readable text files
-  that can be versioned by Git or other version control tools.
-- **Distributed**. No services or servers are required. Metrics are stored in a
-  Git repository as text files, or pointers to files in `DVC` storage.
-- **GitOps API**. logs/summaries are generated through `DVC` using Git commit
-  SHAs or branch names, e.g.: `dvc plots diff --targets dvclive`.
+  <card href="/doc/dvclive/ml-frameworks" heading="ML Frameworks">
+    Use DVCLive alonside your favorite ML Framework
+  </card>
 
-![Plots generated by DVCLive](/uploads/images/2021-02-18/dvclive-diff-html.png)
+  <card href="/doc/dvclive/api-reference" heading="API Reference">
+    See details of all DVCLive's functions
+  </card>
 
-- **Automation**. DVCLive logs/summaries are easy to use by any automation,
-  DevOps, or MLOps tool such as CI/CD (including
-  [CML](https://dvc.org/doc/cml)), custom scripts, or ML platforms.
+</cards>
+
+✅ Please join our [community](/community) or use the [support](/support)
+channels if you have any questions or need specific help. We are very responsive
+⚡.
+
+✅ Check out our [GitHub repository](https://github.com/iterative/dvclive) and
+give us a ⭐ if you like the project!
+
+✅ Contribute to DVCLive [on GitHub](https://github.com/iterative/dvclive) or
+help us improve this [documentation](https://github.com/iterative/dvc.org) 🙏.
diff --git a/...live/user-guide/ml-frameworks/catalyst.md → ...nt/docs/dvclive/ml-frameworks/catalyst.md b/...live/user-guide/ml-frameworks/catalyst.md → ...nt/docs/dvclive/ml-frameworks/catalyst.md
@@ -34,11 +34,11 @@ runner.train(
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/...vclive/user-guide/ml-frameworks/fastai.md → content/docs/dvclive/ml-frameworks/fastai.md b/...vclive/user-guide/ml-frameworks/fastai.md → content/docs/dvclive/ml-frameworks/fastai.md
@@ -33,11 +33,11 @@ learn.fit_one_cycle(
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/...e/user-guide/ml-frameworks/huggingface.md → ...docs/dvclive/ml-frameworks/huggingface.md b/...e/user-guide/ml-frameworks/huggingface.md → ...docs/dvclive/ml-frameworks/huggingface.md
@@ -35,11 +35,11 @@ to the callbacks list passed to your `trainer`:
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/content/docs/dvclive/ml-frameworks/index.md b/content/docs/dvclive/ml-frameworks/index.md
@@ -0,0 +1,21 @@
+# ML Frameworks
+
+DVCLive makes it easy to add experiment tracking capabilities to your existing
+_ML training code_.
+
+We currently support the following _ML Frameworks_:
+
+- [Catalyst](/docs/dvclive/ml-frameworks/catalyst)
+- [Fast.ai](/docs/dvclive/ml-frameworks/fastai)
+- [Hugging Face](/docs/dvclive/ml-frameworks/huggingface)
+- [Keras](/docs/dvclive/ml-frameworks/keras)
+- [LightGBM](/docs/dvclive/ml-frameworks/lightgbm)
+- [MMCV](/docs/dvclive/ml-frameworks/mmcv)
+- [PyTorch](/docs/dvclive/ml-frameworks/pytorch)
+- [TensorFlow](/docs/dvclive/ml-frameworks/tensorflow)
+- [XGBoost](/docs/dvclive/ml-frameworks/xgboost)
+
+The DVCLive team is happy to extend the list with more _ML Frameworks_ as
+needed. Please check the
+[existing issues](https://github.com/iterative/dvclive/issues?q=is%3Aissue+is%3Aopen+label%3Aintegrations)
+or create a new issue to start a discussion!
diff --git a/...dvclive/user-guide/ml-frameworks/keras.md → content/docs/dvclive/ml-frameworks/keras.md b/...dvclive/user-guide/ml-frameworks/keras.md → content/docs/dvclive/ml-frameworks/keras.md
@@ -32,11 +32,11 @@ model.fit(
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/...live/user-guide/ml-frameworks/lightgbm.md → ...nt/docs/dvclive/ml-frameworks/lightgbm.md b/...live/user-guide/ml-frameworks/lightgbm.md → ...nt/docs/dvclive/ml-frameworks/lightgbm.md
@@ -32,11 +32,11 @@ lightgbm.train(
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/.../dvclive/user-guide/ml-frameworks/mmcv.md → content/docs/dvclive/ml-frameworks/mmcv.md b/.../dvclive/user-guide/ml-frameworks/mmcv.md → content/docs/dvclive/ml-frameworks/mmcv.md
@@ -31,7 +31,7 @@ to generate metrics _logs_ and _summaries_ during training.
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/...clive/user-guide/ml-frameworks/pytorch.md → ...ent/docs/dvclive/ml-frameworks/pytorch.md b/...clive/user-guide/ml-frameworks/pytorch.md → ...ent/docs/dvclive/ml-frameworks/pytorch.md
@@ -50,8 +50,8 @@ for epoch in range(args.start_epoch, args.epochs):
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
diff --git a/...ve/user-guide/ml-frameworks/tensorflow.md → .../docs/dvclive/ml-frameworks/tensorflow.md b/...ve/user-guide/ml-frameworks/tensorflow.md → .../docs/dvclive/ml-frameworks/tensorflow.md
@@ -50,8 +50,8 @@ for epoch in range(epochs):
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
diff --git a/...clive/user-guide/ml-frameworks/xgboost.md → ...ent/docs/dvclive/ml-frameworks/xgboost.md b/...clive/user-guide/ml-frameworks/xgboost.md → ...ent/docs/dvclive/ml-frameworks/xgboost.md
@@ -33,11 +33,11 @@ xgboost.train(
 ```
 
 This will generate the metrics logs and summaries as described in the
-[Quickstart](/docs/dvclive/user-guide/quickstart#outputs).
+[Get Started](/docs/dvclive/get-started#outputs).
 
 > 💡Without requiring additional modifications to your training code, you can
 > use DVCLive alongside DVC. See
-> [DVCLive with DVC](/doc/dvclive/user-guide/dvclive-with-dvc) for more info.
+> [DVCLive with DVC](/doc/dvclive/dvclive-with-dvc) for more info.
 
 ## Parameters
 

diff --git a/content/docs/dvclive/user-guide/index.md b/content/docs/dvclive/user-guide/index.md
diff --git a/content/docs/dvclive/user-guide/ml-frameworks/index.md b/content/docs/dvclive/user-guide/ml-frameworks/index.md
diff --git a/content/docs/sidebar.json b/content/docs/sidebar.json
@@ -589,60 +589,53 @@
     "source": "dvclive/index.md",
     "children": [
       {
-        "label": "User Guide",
-        "slug": "user-guide",
-        "source": "dvclive/user-guide/index.md",
+        "label": "Get Started",
+        "slug": "get-started"
+      },
+      {
+        "label": "DVCLive with DVC",
+        "slug": "dvclive-with-dvc"
+      },
+      {
+        "label": "ML Frameworks",
+        "slug": "ml-frameworks",
+        "source": "dvclive/ml-frameworks/index.md",
         "children": [
           {
-            "slug": "quickstart",
-            "label": "Quickstart"
+            "slug": "catalyst",
+            "label": "Catalyst"
           },
           {
-            "label": "DVCLive with DVC",
-            "slug": "dvclive-with-dvc"
+            "slug": "fastai",
+            "label": "Fast.ai"
           },
           {
-            "label": "ML Frameworks",
-            "slug": "ml-frameworks",
-            "source": "dvclive/user-guide/ml-frameworks/index.md",
-            "children": [
-              {
-                "slug": "fastai",
-                "label": "Fast.ai"
-              },
-              {
-                "slug": "catalyst",
-                "label": "Catalyst"
-              },
-              {
-                "slug": "huggingface",
-                "label": "Hugging Face"
-              },
-              {
-                "slug": "keras",
-                "label": "Keras"
-              },
-              {
-                "slug": "lightgbm",
-                "label": "LightGBM"
-              },
-              {
-                "slug": "mmcv",
-                "label": "MMCV"
-              },
-              {
-                "slug": "pytorch",
-                "label": "PyTorch"
-              },
-              {
-                "slug": "tensorflow",
-                "label": "TensorFlow"
-              },
-              {
-                "slug": "xgboost",
-                "label": "XGBoost"
-              }
-            ]
+            "slug": "huggingface",
+            "label": "Hugging Face"
+          },
+          {
+            "slug": "keras",
+            "label": "Keras"
+          },
+          {
+            "slug": "lightgbm",
+            "label": "LightGBM"
+          },
+          {
+            "slug": "mmcv",
+            "label": "MMCV"
+          },
+          {
+            "slug": "pytorch",
+            "label": "PyTorch"
+          },
+          {
+            "slug": "tensorflow",
+            "label": "TensorFlow"
+          },
+          {
+            "slug": "xgboost",
+            "label": "XGBoost"
           }
         ]
       },

diff --git a/static/img/dvclive-html.gif b/static/img/dvclive-html.gif