Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

docs: add desc field #1951

Merged
merged 1 commit into from
Nov 26, 2020
Merged

docs: add desc field #1951

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
5 changes: 4 additions & 1 deletion content/docs/command-reference/add.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -7,7 +7,7 @@ file.

```usage
usage: dvc add [-h] [-q | -v] [-R] [--no-commit] [--external]
[--file <filename>] [--glob]
[--file <filename>] [--glob] [--desc <text>]
targets [targets ...]

positional arguments:
Expand Down Expand Up @@ -148,6 +148,9 @@ directory symlinks.
pattern as specified by `target`. Shell-style wildcards are supported: `*`,
`?`, `[seq]`, `[!seq]`, and `**`.

- `--desc <text>` - 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
Expand Down
4 changes: 4 additions & 0 deletions content/docs/command-reference/import-url.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -11,6 +11,7 @@ changes in the remote data source. Creates a `.dvc` file.

```usage
usage: dvc import-url [-h] [-q | -v] [--file <filename>] [--no-exec]
[--desc <text>]
url [out]

positional arguments:
Expand Down Expand Up @@ -129,6 +130,9 @@ source.
`.dvc` file. You can use `dvc commit <out>.dvc` if you need the hashes in the
new `.dvc` file and save existing data to the cache.

- `--desc <text>` - 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
Expand Down
5 changes: 4 additions & 1 deletion content/docs/command-reference/import.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ the import.
```usage
usage: dvc import [-h] [-q | -v]
[-o <path>] [--file <filename>]
[--rev <commit>] [--no-exec]
[--rev <commit>] [--no-exec] [--desc <text>]
url path

positional arguments:
Expand Down Expand Up @@ -109,6 +109,9 @@ repo at `url`) are not supported.
is saved into the `.dvc` file. You can use `dvc commit <out>.dvc` if you need
the hashes in the new `.dvc` file and save existing data to the cache.

- `--desc <text>` - 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
Expand Down
5 changes: 4 additions & 1 deletion content/docs/command-reference/run.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 <text>]
command

positional arguments:
Expand Down Expand Up @@ -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 <text>` - 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
Expand Down
9 changes: 8 additions & 1 deletion content/docs/user-guide/dvc-files-and-directories.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -37,6 +37,7 @@ edit, or even created manually. Here is a sample:
outs:
- md5: a304afb96060aad90176268345e10355
path: data.xml
desc: cats and dogs dataset

# Comments and user metadata are supported.
meta:
Expand Down Expand Up @@ -74,6 +75,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 <abbr>cached</abbr> (`true`
by default, if not present). See the `--no-commit` option of `dvc add`.
- `desc`: User description for this output. This doesn't affect any DVC
operations.
Comment on lines 76 to +79
Copy link
Contributor

@jorgeorpinel jorgeorpinel Nov 30, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Also, is it correct that for .dvc files desc is a subfield inside outs? Seems odd since it's a top-level field in dvc.yaml files.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It is both.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, didn't get that. I guess you're saying that yes, this is correct: desc is at the outs level in .dvc files, but at the top-level for dvc.yaml. This "inconsistency" seems unintuitive to me.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

desc can be for stage or for specific output

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@jorgeorpinel Let's not focus on this too much, this is minor for docs.

Copy link
Contributor

@jorgeorpinel jorgeorpinel Dec 3, 2020 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

desc may be minor but 1. that doesn't mean its OK to have an error in docs if we see it (not the case here but I wasn't sure until now) and 2. this is making me realize the way we present outputs vs dvc.yaml in https://dvc.org/doc/user-guide/dvc-files-and-directories is confusing because outputs are only expanded on in the .dvc file section... which is kind of major. I'll address that elsewhere.


A _dependency entry_ (`deps`) consists of these fields:

Expand Down Expand Up @@ -128,12 +131,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
Expand Down Expand Up @@ -173,6 +178,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`.

Expand Down