docs: add desc field

iterative · Nov 17, 2020 · c45eabf · c45eabf
1 parent 8d4fe32
commit c45eabf
Show file tree

Hide file tree

Showing 3 changed files with 10 additions and 2 deletions.
diff --git a/content/docs/command-reference/add.md b/content/docs/command-reference/add.md
@@ -7,7 +7,7 @@ file.
 
 ```usage
 usage: dvc add [-h] [-q | -v] [-R] [--no-commit] [--external]
-               [--file <filename>] [--glob]
+               [--file <filename>] [--glob] [--desc <description>]
                targets [targets ...]
 
 positional arguments:
@@ -148,6 +148,8 @@ directory symlinks.
   pattern as specified by `target`. Shell-style wildcards are supported: `*`,
   `?`, `[seq]`, `[!seq]`, and `**`.
 
+- `--desc` - arbitrary string description for generated `.dvc` file.
+
 - `-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/run.md b/content/docs/command-reference/run.md
@@ -12,7 +12,7 @@ usage: dvc run [-h] [-q | -v] -n <name> [-d <path>] [-o <path>]
                [-w <path>] [--no-exec] [-f]
                [--no-run-cache] [--no-commit]
                [--outs-persist <path>] [--outs-persist-no-cache <path>]
-               [--always-changed] [--external]
+               [--always-changed] [--external] [--desc <description>]
                command
 
 positional arguments:
@@ -263,6 +263,8 @@ $ dvc run -n my_stage './my_script.sh $MYENVVAR'
 - `--external` - allow outputs that are outside of the DVC repository. See
   [Managing External Data](/doc/user-guide/managing-external-data).
 
+- `--desc` - arbitrary string description for this stage.
+
 - `-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/user-guide/dvc-files-and-directories.md b/content/docs/user-guide/dvc-files-and-directories.md
@@ -34,6 +34,7 @@ They use a simple [YAML](https://yaml.org/) format, meant to be easy to read,
 edit, or even created manually. Here is a sample:
 
 ```yaml
+desc: cats and dogs dataset
 outs:
   - md5: a304afb96060aad90176268345e10355
     path: data.xml
@@ -60,6 +61,7 @@ meta:
 - `meta` (optional): Arbitrary metadata can be added manually with this field.
   Any YAML contents is supported. `meta` contents are ignored by DVC, but they
   can be meaningful for user processes that read `.dvc` files.
+- `desc` (optional): Arbitrary string description for this `.dvc` file.
 
 An _output entry_ (`outs`) consists of these fields:
 
@@ -128,6 +130,7 @@ stages:
     metrics:
       - performance.json
   training:
+    desc: train your model
     cmd: python train.py
     deps:
       - train.py
@@ -173,6 +176,7 @@ the possible following fields:
 - `meta` (optional): Arbitrary metadata can be added manually with this field.
   Any YAML contents is supported. `meta` contents are ignored by DVC, but they
   can be meaningful for user processes that read or write `.dvc` files directly.
+- `desc` (optional): Arbitrary string description for this stage.
 
 `dvc.yaml` files also support `# comments`.