From e49faad59f8889405d25dba6ce4d5d022b5a2954 Mon Sep 17 00:00:00 2001 From: Ruslan Kuprieiev Date: Tue, 17 Nov 2020 03:00:26 +0200 Subject: [PATCH] docs: add desc field for stages and outs Per https://github.com/iterative/dvc/pull/4901 --- content/docs/command-reference/add.md | 5 ++++- content/docs/command-reference/import-url.md | 4 ++++ content/docs/command-reference/import.md | 5 ++++- content/docs/command-reference/run.md | 5 ++++- content/docs/user-guide/dvc-files-and-directories.md | 11 ++++++++++- 5 files changed, 26 insertions(+), 4 deletions(-) diff --git a/content/docs/command-reference/add.md b/content/docs/command-reference/add.md index 4d49e0c9fe8..de18dcbb1fd 100644 --- 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 ] [--glob] + [--file ] [--glob] [--desc ] targets [targets ...] positional arguments: @@ -148,6 +148,9 @@ directory symlinks. pattern as specified by `target`. Shell-style wildcards are supported: `*`, `?`, `[seq]`, `[!seq]`, and `**`. +- `--desc ` - user description of the data (optional). This doesn't affect + any DVC operations. + - `-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/import-url.md b/content/docs/command-reference/import-url.md index 5c18fa65dff..ef0bd950418 100644 --- a/content/docs/command-reference/import-url.md +++ b/content/docs/command-reference/import-url.md @@ -11,6 +11,7 @@ changes in the remote data source. Creates a `.dvc` file. ```usage usage: dvc import-url [-h] [-q | -v] [--file ] [--no-exec] + [--desc ] url [out] positional arguments: @@ -129,6 +130,9 @@ source. `.dvc` file. You can use `dvc commit .dvc` if you need the hashes in the new `.dvc` file and save existing data to the cache. +- `--desc ` - user description of the data (optional). This doesn't + affect any DVC operations. + - `-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/import.md b/content/docs/command-reference/import.md index f435d8a0173..67ff5bcf68e 100644 --- a/content/docs/command-reference/import.md +++ b/content/docs/command-reference/import.md @@ -12,7 +12,7 @@ the import. ```usage usage: dvc import [-h] [-q | -v] [-o ] [--file ] - [--rev ] [--no-exec] + [--rev ] [--no-exec] [--desc ] url path positional arguments: @@ -109,6 +109,9 @@ repo at `url`) are not supported. is saved into the `.dvc` file. You can use `dvc commit .dvc` if you need the hashes in the new `.dvc` file and save existing data to the cache. +- `--desc ` - user description of the data (optional). This doesn't affect + any DVC operations. + - `-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 index 8eb6714f81b..08d937c5b82 100644 --- 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 [-d ] [-o ] [-w ] [--no-exec] [-f] [--no-run-cache] [--no-commit] [--outs-persist ] [--outs-persist-no-cache ] - [--always-changed] [--external] + [--always-changed] [--external] [--desc ] command positional arguments: @@ -263,6 +263,9 @@ $ 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 ` - user description of the stage (optional). This doesn't + affect any DVC operations. + - `-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 index 7f95efb29df..c1d006e07b0 100644 --- 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,8 @@ 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): User description for this `.dvc` file. This doesn't affect + any DVC operations. An _output entry_ (`outs`) consists of these fields: @@ -74,6 +77,8 @@ An _output entry_ (`outs`) consists of these fields: - `nfiles`: If a directory, number of files inside. - `cache`: Whether or not this file or directory is cached (`true` by default, if not present). See the `--no-commit` option of `dvc add`. +- `meta`: User description for this output. This doesn't affect any DVC + operations. A _dependency entry_ (`deps`) consists of these fields: @@ -128,12 +133,14 @@ stages: metrics: - performance.json training: + desc: train your model cmd: python train.py deps: - train.py - features outs: - - model.pkl + - model.pkl: + desc: my model description plots: - logs.csv: x: epoch @@ -173,6 +180,8 @@ 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): User description for this stage. This doesn't affect any + DVC operations. `dvc.yaml` files also support `# comments`.