ref: exp cmd index, make_checkpoint() fn

config/prismjs/dvc-commands.js

@@ -42,6 +42,8 @@ module.exports = [
   'gc',
   'freeze',
   'fetch',
+  'exp',
+  'experiments',
   'doctor',
   'diff',
   'destroy',

content/docs/api-reference/make_checkpoint.md

@@ -0,0 +1,83 @@
+# dvc.api.make_checkpoint()
+
+Make an
+[in-code checkpoint](/doc/user-guide/experiment-management#checkpoints-in-source-code).
+
+```py
+def make_checkpoint()
+```
+
+#### Usage:
+
+```py
+from dvc.api import make_checkpoint
+
+while True:
+    # ... write a stage output
+    make_checkpoint()
+```
+
+## Description
+
+To track successive steps in a longer
+[experiment](/doc/user-guide/experiment-management), you can write your code so
+it registers checkpoints with DVC during runtime. This function should be called
+by the code in stages executes by `dvc exp run` (see `cmd` field of `dvc.yaml`).
+
+> Note that for non-Python code, the alternative is to write a
+> `.dvc/tmp/DVC_CHECKPOINT` signal file.
+
+## Exceptions
+
+None
+
+## Example: Mark a checkpoint every 100 iterations
+
+Let's consider the following `dvc.yaml` file:
+
+```yaml
+stages:
+  foo:
+    cmd: python src/mystage.py
+    params:
+      - start
+    outs:
+      - int.txt:
+          checkpoint: true
+```
+
+> See `dvc params` for information on stage parameters.
+
+Here's the example code that the stage above will execute. It continuously
+increments an integer value in the `int.txt` file, starting at the `start`
+param. It makes a checkpoint with `dvc exp` every time the value adds 100:
+
+```py
+import os
+from ruamel.yaml import YAML
+from dvc.api import make_checkpoint
+
+output_file = "int.txt"
+
+with open("params.yaml") as fobj:
+    params = yaml.load(fobj)
+start = params.get("start", 0)
+
+while True:
+    try:
+        if os.path.exists(output_file):
+            with open(output_file, "r") as fobj:
+                try:
+                    data = fobj.read()
+                    iter_ = int(data) + 1
+                except ValueError:
+                    iter_ = start
+        else:
+            iter_ = start
+
+        with open(output_file, "w") as fobj:
+            fobj.write(f"{iter_}")
+
+        if iter_ % 100 == 0:
+            make_checkpoint()
+```

content/docs/command-reference/exp/index.md

@@ -0,0 +1,39 @@
+# dvc experiments
+
+> Aliased to `dvc exp`.
+
+A set of commands to generate and manage experiments:
+[run](/doc/command-reference/exp/run), [show](/doc/command-reference/exp/show),
+[diff](/doc/command-reference/exp/diff),
+[apply](/doc/command-reference/exp/apply),
+[branch](/doc/command-reference/exp/branch),
+[list](/doc/command-reference/exp/list),
+[resume](/doc/command-reference/exp/resume),
+[push](/doc/command-reference/exp/list),
+[pull](/doc/command-reference/exp/pull), and
+[gc](/doc/command-reference/exp/gc).
+
+## Synopsis
+
+```usage
+usage: dvc experiments [-h] [-q | -v]
+       {show,apply,diff,run,resume,res,gc,branch,list,push,pull} ...
+
+positional arguments:
+  COMMAND
+    show          Print experiments.
+    apply         Apply the changes from an experiment to your workspace.
+    diff          Show changes between experiments in the DVC repository.
+    run           Reproduce complete or partial experiment pipelines.
+    resume (res)  Resume checkpoint experiments.
+    gc            Garbage collect unneeded experiments.
+    branch        Promote an experiment to a Git branch.
+    list          List local and remote experiments.
+    push          Push a local experiment to a Git remote.
+    pull          Pull an experiment from a Git remote.
+```
+
+## Description
+
+> Note that DVC assumes that experiments are deterministic (see **Avoiding
+> unexpected behavior** in `dvc run`).

content/docs/sidebar.json

@@ -214,6 +214,11 @@
         "label": "doctor",
         "slug": "doctor"
       },
+      {
+        "label": "experiments",
+        "slug": "exp",
+        "source": "exp/index.md"
+      },
       {
         "label": "fetch",
         "slug": "fetch",
@@ -399,6 +404,10 @@
       {
         "slug": "read",
         "label": "read()"
+      },
+      {
+        "slug": "make_checkpoint",
+        "label": "make_checkpoint()"
       }
     ]
   },