From 8c97bb1d6677b5b83556d43a10c3709bd31cbbff Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Mon, 3 Feb 2020 14:27:31 -0600 Subject: [PATCH 1/4] cmd ref: consistent spacing in positional arguments (Synopsis) section from https://github.com/iterative/dvc.org/pull/931#pullrequestreview-348279331 --- public/static/docs/command-reference/add.md | 2 +- public/static/docs/command-reference/checkout.md | 4 ++-- public/static/docs/command-reference/commit.md | 4 ++-- public/static/docs/command-reference/config.md | 4 ++-- public/static/docs/command-reference/diff.md | 7 +++---- public/static/docs/command-reference/fetch.md | 4 ++-- public/static/docs/command-reference/get-url.md | 4 ++-- public/static/docs/command-reference/get.md | 4 ++-- public/static/docs/command-reference/import-url.md | 4 ++-- public/static/docs/command-reference/import.md | 4 ++-- 10 files changed, 20 insertions(+), 21 deletions(-) diff --git a/public/static/docs/command-reference/add.md b/public/static/docs/command-reference/add.md index f739c54ac6..c9dc2af363 100644 --- a/public/static/docs/command-reference/add.md +++ b/public/static/docs/command-reference/add.md @@ -10,7 +10,7 @@ usage: dvc add [-h] [-q | -v] [-R] [--no-commit] [-f FILE] targets [targets ...] positional arguments: - targets Input files/directories to add. + targets Input files/directories to add. ``` ## Description diff --git a/public/static/docs/command-reference/checkout.md b/public/static/docs/command-reference/checkout.md index 661bdb3955..67f3c8a37b 100644 --- a/public/static/docs/command-reference/checkout.md +++ b/public/static/docs/command-reference/checkout.md @@ -10,8 +10,8 @@ usage: dvc checkout [-h] [-q | -v] [-d] [-R] [-f] [--relink] [targets [targets ...]] positional arguments: - targets DVC-files to checkout. Optional. (Finds all - DVC-files in the workspace by default.) + targets DVC-files to checkout. Optional. (Finds all + DVC-files in the workspace by default.) ``` ## Description diff --git a/public/static/docs/command-reference/commit.md b/public/static/docs/command-reference/commit.md index 78022c14d5..868dae01a4 100644 --- a/public/static/docs/command-reference/commit.md +++ b/public/static/docs/command-reference/commit.md @@ -11,8 +11,8 @@ usage: dvc commit [-h] [-q | -v] [-f] [-d] [-R] [targets [targets ...]] positional arguments: - targets DVC-files to commit. Optional. (Finds all - DVC-files in the workspace by default.) + targets DVC-files to commit. Optional. (Finds all DVC-files + in the workspace by default.) ``` ## Description diff --git a/public/static/docs/command-reference/config.md b/public/static/docs/command-reference/config.md index aeb88b1ea0..29f3d3b47d 100644 --- a/public/static/docs/command-reference/config.md +++ b/public/static/docs/command-reference/config.md @@ -9,8 +9,8 @@ usage: dvc config [-h] [--global] [--system] [--local] [-q | -v] [-u] name [value] positional arguments: - name Option name. - value Option value. + name Option name. + value Option value. ``` ## Description diff --git a/public/static/docs/command-reference/diff.md b/public/static/docs/command-reference/diff.md index 507007ebfd..b1a1665895 100644 --- a/public/static/docs/command-reference/diff.md +++ b/public/static/docs/command-reference/diff.md @@ -12,10 +12,9 @@ narrowed down to specific target files and directories under DVC control. usage: dvc diff [-h] [-q | -v] [-t TARGET] a_ref [b_ref] positional arguments: - a_ref Git reference from which diff calculates - b_ref Git reference until which diff calculates, if - omitted diff shows the difference between - current HEAD and a_ref + a_ref Git reference from which diff calculates + b_ref Git reference until which diff calculates, if omitted diff + shows the difference between current HEAD and a_ref ``` ## Description diff --git a/public/static/docs/command-reference/fetch.md b/public/static/docs/command-reference/fetch.md index 24ae902c08..a0ac224a07 100644 --- a/public/static/docs/command-reference/fetch.md +++ b/public/static/docs/command-reference/fetch.md @@ -11,8 +11,8 @@ usage: dvc fetch [-h] [-q | -v] [-j JOBS] [--show-checksums] [targets [targets ...]] positional arguments: - targets Limit command scope to these DVC-files. Using -R, - directories to search DVC-files in can also be given. + targets Limit command scope to these DVC-files. Using -R, + directories to search DVC-files in can also be given. ``` ## Description diff --git a/public/static/docs/command-reference/get-url.md b/public/static/docs/command-reference/get-url.md index ac910799c7..bc9b3bee86 100644 --- a/public/static/docs/command-reference/get-url.md +++ b/public/static/docs/command-reference/get-url.md @@ -12,8 +12,8 @@ Download a file or directory from a supported URL (for example `s3://`, usage: dvc get-url [-h] [-q | -v] url [out] positional arguments: - url (See supported URLs in the description.) - out Destination path to put data in. + url (See supported URLs in the description.) + out Destination path to put data to. ``` ## Description diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md index 33f29a385b..167b9f2a61 100644 --- a/public/static/docs/command-reference/get.md +++ b/public/static/docs/command-reference/get.md @@ -12,8 +12,8 @@ repository into the current working directory. usage: dvc get [-h] [-q | -v] [-o [OUT]] [--rev [REV]] url path positional arguments: - url Location of DVC or Git repository to download from. - path Path to a file or directory within the repository. + url Location of DVC or Git repository to download from. + path Path to a file or directory within the repository. ``` ## Description diff --git a/public/static/docs/command-reference/import-url.md b/public/static/docs/command-reference/import-url.md index 50af72c024..cc55e1e0a9 100644 --- a/public/static/docs/command-reference/import-url.md +++ b/public/static/docs/command-reference/import-url.md @@ -13,8 +13,8 @@ changes in the remote data source. Creates a DVC-file. usage: dvc import-url [-h] [-q | -v] [-f FILE] url [out] positional arguments: - url (See supported URLs in the description.) - out Destination path to put data in. + url (See supported URLs in the description.) + out Destination path to put files to. ``` ## Description diff --git a/public/static/docs/command-reference/import.md b/public/static/docs/command-reference/import.md index d7c9fed724..cf86488d9c 100644 --- a/public/static/docs/command-reference/import.md +++ b/public/static/docs/command-reference/import.md @@ -15,8 +15,8 @@ import. usage: dvc import [-h] [-q | -v] [-o [OUT]] [--rev [REV]] url path positional arguments: - url Location of DVC or Git repository to download from. - path Path to a file or directory within the repository. + url Location of DVC or Git repository to download from. + path Path to a file or directory within the repository. ``` ## Description From 0e5332cd947d38224daaaaead3b0d11e3de3e48c Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Mon, 3 Feb 2020 20:13:31 -0600 Subject: [PATCH 2/4] cmd ref: typo in get per https://github.com/iterative/dvc.org/pull/931#pullrequestreview-352683085 --- public/static/docs/command-reference/get.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/public/static/docs/command-reference/get.md b/public/static/docs/command-reference/get.md index 167b9f2a61..3d155b32fa 100644 --- a/public/static/docs/command-reference/get.md +++ b/public/static/docs/command-reference/get.md @@ -37,7 +37,7 @@ The `path` argument of this command is used to specify the location of the target to be downloaded within the source repository at `url`. It can point to any file or directory in there, including outputs tracked by DVC, as well as files tracked by Git. Note that for DVC repos, the target should be -found in one of the [DVC-files](/doc/user-guide/dvc-file-format) pf the project. +found in one of the [DVC-files](/doc/user-guide/dvc-file-format) of the project. The project should also have a default [DVC remote](/doc/command-reference/remote), containing the actual data. From 7ef096851871a76b6b621883e51ffdb32270c087 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Mon, 3 Feb 2020 20:17:26 -0600 Subject: [PATCH 3/4] glossary: removed unnecessary sentence in project def. per https://github.com/iterative/dvc.org/pull/931#discussion_r374312624 --- public/static/docs/glossary.js | 4 +--- 1 file changed, 1 insertion(+), 3 deletions(-) diff --git a/public/static/docs/glossary.js b/public/static/docs/glossary.js index 0f58e63aa9..bb6d10bc59 100644 --- a/public/static/docs/glossary.js +++ b/public/static/docs/glossary.js @@ -26,9 +26,7 @@ Initialized by running \`dvc init\` in the **workspace** (typically in a Git repository). It will contain the [\`.dvc/\` directory](/doc/user-guide/dvc-files-and-directories) and [DVC-files](/doc/user-guide/dvc-file-format) created with commands such as -\`dvc add\` or \`dvc run\`. Some DVC commands require it to be in a Git repo – -explained in each [command reference](/doc/command-reference) but usually -obvious from the context. +\`dvc add\` or \`dvc run\`. ` }, { From 1551b4b93828358284030386dc7057b134fbbee6 Mon Sep 17 00:00:00 2001 From: Jorge Orpinel Date: Mon, 3 Feb 2020 20:23:31 -0600 Subject: [PATCH 4/4] cmd ref: refactor notes in get-url and import-url per https://github.com/iterative/dvc.org/pull/931#pullrequestreview-352682755 --- .../static/docs/command-reference/get-url.md | 12 ++--- .../docs/command-reference/import-url.md | 52 ++++++++----------- 2 files changed, 28 insertions(+), 36 deletions(-) diff --git a/public/static/docs/command-reference/get-url.md b/public/static/docs/command-reference/get-url.md index bc9b3bee86..1a45e8c992 100644 --- a/public/static/docs/command-reference/get-url.md +++ b/public/static/docs/command-reference/get-url.md @@ -42,11 +42,6 @@ DVC supports several types of (local or) remote locations (protocols): | `hdfs` | HDFS to file\* | `hdfs://user@example.com/path/to/data.csv` | | `http` | HTTP to file\* | `https://example.com/path/to/data.csv` | -> \* HDFS and HTTP **do not** support downloading entire directories, only -> single files. - - - > If you installed DVC via `pip` and plan to use cloud services as remote > storage, you might need to install these optional dependencies: `[s3]`, > `[azure]`, `[gdrive]`, `[gs]`, `[oss]`, `[ssh]`. Alternatively, use `[all]` to @@ -55,8 +50,8 @@ DVC supports several types of (local or) remote locations (protocols): -> See `dvc get` to download data/model files or directories from other DVC -> repositories (e.g. GitHub URLs). +\* HDFS and HTTP **do not** support downloading entire directories, only single +files. Another way to understand the `dvc get-url` command is as a tool for downloading data files. On GNU/Linux systems for example, instead of `dvc get-url` with @@ -66,6 +61,9 @@ HTTP(S) it's possible to instead use: $ wget https://example.com/path/to/data.csv ``` +> See `dvc get` to download data/model files or directories from other DVC +> repositories (e.g. GitHub URLs). + ## Options - `-h`, `--help` - prints the usage/help message, and exit. diff --git a/public/static/docs/command-reference/import-url.md b/public/static/docs/command-reference/import-url.md index cc55e1e0a9..e5e7ca8207 100644 --- a/public/static/docs/command-reference/import-url.md +++ b/public/static/docs/command-reference/import-url.md @@ -44,20 +44,15 @@ determine whether the local copy is out of date. DVC supports several types of (local or) remote locations (protocols): -| Type | Description | `url` format | -| -------- | ----------------------------------------------------- | ------------------------------------------ | -| `local` | Local path | `/path/to/local/data` | -| `s3` | Amazon S3 | `s3://mybucket/data` | -| `gs` | Google Storage | `gs://mybucket/data` | -| `ssh` | SSH server | `ssh://user@example.com:/path/to/data` | -| `hdfs` | HDFS to file\* | `hdfs://user@example.com/path/to/data.csv` | -| `http` | HTTP to file with _strong ETag_ (explanation below)\* | `https://example.com/path/to/data.csv` | -| `remote` | Remote path (see explanation below) | `remote://myremote/path/to/data` | - -> \* HDFS and HTTP **do not** support downloading entire directories, only -> single files. - - +| Type | Description | `url` format | +| -------- | --------------------------------------------------- | ------------------------------------------ | +| `local` | Local path | `/path/to/local/data` | +| `s3` | Amazon S3 | `s3://mybucket/data` | +| `gs` | Google Storage | `gs://mybucket/data` | +| `ssh` | SSH server | `ssh://user@example.com:/path/to/data` | +| `hdfs` | HDFS to file (explanation below) | `hdfs://user@example.com/path/to/data.csv` | +| `http` | HTTP to file with _strong ETag_ (explanation below) | `https://example.com/path/to/data.csv` | +| `remote` | Remote path (see explanation below) | `remote://myremote/path/to/data` | > If you installed DVC via `pip` and plan to use cloud services as remote > storage, you might need to install these optional dependencies: `[s3]`, @@ -65,24 +60,20 @@ DVC supports several types of (local or) remote locations (protocols): > include them all. The command should look like this: `pip install "dvc[s3]"`. > (This example installs `boto3` library along with DVC to support S3 storage.) - - -> In case of HTTP, -> [strong ETag](https://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation) -> is necessary to track if the specified remote file (URL) changed to download -> it again. +Specific explanations: - +- HDFS and HTTP **do not** support downloading entire directories, only single + files. -> `remote://myremote/path/to/file` notation just means that a DVC -> [remote](/doc/command-reference/remote) `myremote` is defined and when DVC is -> running. DVC automatically expands this URL into a regular S3, SSH, GS, etc -> URL by appending `/path/to/file` to the `myremote`'s configured base path. +- In case of HTTP, + [strong ETag](https://en.wikipedia.org/wiki/HTTP_ETag#Strong_and_weak_validation) + is necessary to track if the specified remote file (URL) changed to download + it again. - - -> See `dvc import` to download and tack data/model files or directories from -> other DVC repositories (e.g. GitHub URLs). +- `remote://myremote/path/to/file` notation just means that a DVC + [remote](/doc/command-reference/remote) `myremote` is defined and when DVC is + running. DVC automatically expands this URL into a regular S3, SSH, GS, etc + URL by appending `/path/to/file` to the `myremote`'s configured base path. Another way to understand the `dvc import-url` command is as a short-cut for a more verbose `dvc run` command. This is discussed in the @@ -112,6 +103,9 @@ Note that import stages are considered always locked, meaning that if you run `dvc repro`, they won't be updated. Use `dvc update` on them to bring the import up to date from the external data source. +> See `dvc import` to download and tack data/model files or directories from +> other DVC repositories (e.g. GitHub URLs). + ## Options - `-f`, `--file` - specify name of the DVC-file it generates. By default the