[WIP] cmd-ref: document exp init (#3015)

* cmd-ref: document exp init

* Restyle [WIP] cmd-ref: document exp init (#3016)

Co-authored-by: Restyled.io <[email protected]>

* Apply suggestions from code review

* Restyled by prettier (#3018)

Co-authored-by: Restyled.io <[email protected]>

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

* Restyled by prettier (#3048)

Co-authored-by: Restyled.io <[email protected]>

* updates

* document config

* cmd-ref exp init: updates for initial merge

Co-authored-by: restyled-io[bot] <32688539+restyled-io[bot]@users.noreply.github.com>
Co-authored-by: Restyled.io <[email protected]>
Co-authored-by: Jorge Orpinel <[email protected]>
Co-authored-by: dberenbaum <[email protected]>

content/docs/command-reference/config.md

@@ -221,6 +221,30 @@ connection settings, and configuring a remote is the way that can be done.
 > hash overlaps: the hash of an external <abbr>output</abbr> could collide with
 > that of a local file with different content.
 
+### exp
+
+This section overrides default configured workspace paths in `dvc exp init`,
+that helps to avoid repeating these paths if all of your projects share a
+similar structure.
+
+The section contains following options, which are only used as a default and can
+be overidden explicitly through CLI arguments or through responses in prompts
+(in `--interactive` mode).
+
+- `exp.code` - path to your source file or directory.
+
+- `exp.data` - path to your data file or directory to track.
+
+- `exp.models` - path to your models file or directory.
+
+- `exp.metrics` - path to your metrics file.
+
+- `exp.params` - path to your parameters file.
+
+- `exp.plots` - path to your plots file or directory.
+
+- `exp.live` - path to your dvclive outputs.
+
 ### state
 
 > 📖 See

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

@@ -3,7 +3,8 @@
 _New in DVC 2.0 (see `dvc version`)_
 
 A set of commands to generate and manage <abbr>experiments</abbr>:
-[run](/doc/command-reference/exp/run), [show](/doc/command-reference/exp/show),
+[init](/doc/command-reference/exp/init), [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),
@@ -20,7 +21,7 @@ A set of commands to generate and manage <abbr>experiments</abbr>:
 
 ```usage
 usage: dvc exp [-h] [-q | -v]
-          {show,apply,diff,run,gc,branch,list,push,pull,remove}
+          {show,apply,diff,run,gc,branch,list,push,pull,remove,init}
           ...
 
 positional arguments:
@@ -37,6 +38,7 @@ positional arguments:
     push                Push a local experiment to a Git remote.
     pull                Pull an experiment from a Git remote.
     remove              Remove local experiments.
+    init                Initialize experiments.
 ```
 
 ## Description

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

@@ -0,0 +1,127 @@
+# exp init
+
+Codify project using [DVC metafiles] to run [experiments].
+
+## Synopsis
+
+```usage
+usage: dvc exp init [-h] [-q | -v] [--run] [--interactive] [-f]
+                    [--explicit] [--name NAME] [--code CODE]
+                    [--data DATA] [--models MODELS] [--params PARAMS]
+                    [--metrics METRICS] [--plots PLOTS] [--live LIVE]
+                    [--type {default,dl}]
+                    [command]
+```
+
+## Description
+
+`dvc exp init` helps you quickly get started with experiments. It reduces
+boilerplate for initializing [pipeline](/doc/command-reference/dag) stages in a
+`dvc.yaml` file by assuming defaults about the location of your data,
+[parameters](/doc/command-reference/params), source code, models,
+[metrics](/doc/command-reference/metrics) and
+[plots](/doc/command-reference/plots), which can be customized through config.
+
+It also offers guided `--interactive` mode for creating a stage to be
+[`exp run`](/doc/command-reference/exp/run) later. `dvc exp init` supports
+creating different types of stages, eg: `dl` if you are doing deep learning,
+which uses [dvclive](/doc/dvclive) to monitor and checkpoint progress during
+training of machine learning models.
+
+This command is intended to be a quick way to start running experiments. To
+create more complex stages and pipeliens, use `dvc stage add`.
+
+### The `command` argument
+
+The `command` argument is optional, if you are using `--interactive` mode. The
+`command` sent to `dvc exp init` can be anything your terminal would accept and
+run directly, for example a shell built-in, expression, or binary found in
+`PATH`. Please remember that any flags sent after the `command` are interpreted
+by the command itself, not by `dvc exp init`.
+
+⚠️ While DVC is platform-agnostic, the commands defined in your
+[pipeline](/doc/command-reference/dag) stages may only work on some operating
+systems and require certain software packages to be installed.
+
+Wrap the command with double quotes `"` if there are special characters in it
+like `|` (pipe) or `<`, `>` (redirection), otherwise they would apply to
+`dvc exp init` itself. Use single quotes `'` instead if there are environment
+variables in it that should be evaluated dynamically. Examples:
+
+```dvc
+$ dvc exp init "./a_script.sh > /dev/null 2>&1"
+$ dvc exp init './another_script.sh $MYENVVAR'
+```
+
+## Options
+
+- `-i`, `--interactive` - prompts user for the command to execute and different
+  paths for tracking outputs and dependencies, unless they are provided through
+  arguments explicitly. Interactive mode allows users to set those locations
+  from default values or omit them.
+
+- `--explicit` - `dvc exp init` assumes default location of your outputs and
+  dependencies (which can be overriden from the config). By using `--explicit`,
+  it will not use those default values while initializing experiments. In
+  `--interactive` mode, prompt won't set default value and all the values for
+  the prompt needs to be explicitly provided, or omitted.
+
+- `--code` - override the a path to your source file or directory which your
+  experiment depends on. The default is `src` directory for your code.
+
+- `--data` - override the path to your data file or directory to track, which
+  your experiment depends on. The default is `data` directory.
+
+- `--params` - override the path to
+  [parameter dependencies](/doc/command-reference/params) which your experiment
+  depends on. The default parameters file name is `params.yaml`. Note that
+  `dvc exp init` may fail if the parameters file does not exist at the time of
+  the invocation, as DVC reads the file to find parameters to track for the
+  stage.
+
+- `--model` - override the path to your models file or directory to track, which
+  your experiment produces. `dvc exp init` assumes `models` directory by
+  default.
+
+- `--metrics` - override the path to metrics file to track, which your
+  experiment produces. Default is `metrics.json` file.
+
+- `--plots` - override the path to plots file or directory, which your
+  experiment produces. The default is `plots`.
+
+- `--live` - override the directory `path` for [DVCLive](/doc/dvclive), which
+  your experiment will write logs to. The default is `dvclive` directory, which
+  only comes to effect when used with `--type=dl`.
+
+- `--type` - selects the type of the stage to create. Currently it provides two
+  different kinds of stages: `default` and `dl`. If unspecified, `default` stage
+  is created.
+
+  `default` stage creates a stage with `metrics` and `plots` tracked by DVC
+  itself, and does not track live-created artifacts (unless explicitly
+  specified).
+
+  `dl` stage is intended for use in deep-learning scenarios, where metrics and
+  plots are tracked by [dvclive](/doc/dvclive) and supports tracking progress
+  while training a deep-learning model with
+  [checkpoints](/doc/command-reference/exp/run#checkpoints).
+
+- `-n <stage>`, `--name <stage>` - specify a custom name for the stage generated
+  by this command (e.g. `-n train`). By default, the name of the stage depends
+  on `--type` of the stage that is being created. If
+  `--type=default, the name of the stage will be `default`, and in case of `--type=dl`, the name of the stage will be `dl`.
+
+  Note that the stage name can only contain letters, numbers, dash `-` and
+  underscore `_`.
+
+- `-f`, `--force` - overwrite an existing stage in `dvc.yaml` file without
+  asking for confirmation.
+
+- `--run` - runs the experiment after initializing it.
+
+- `-h`, `--help` - prints the usage/help message, and exit.
+
+- `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no
+  problems arise, otherwise 1.
+
+- `-v`, `--verbose` - displays detailed tracing information.

content/docs/sidebar.json

@@ -260,6 +260,10 @@
             "label": "exp show",
             "slug": "show"
           },
+          {
+            "label": "exp init",
+            "slug": "init"
+          },
           {
             "label": "exp diff",
             "slug": "diff"