Merge pull request #787 from iterative/cmd-ref

Improve readability of multi-paragraph cmd options.

static/docs/command-reference/add.md

@@ -94,12 +94,11 @@ and make your project reproducible.
   description.
 
 - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an
-  entry is added to `.dvc/state`, while nothing is added to the cache. This is
+  entry is added to `.dvc/state`, while nothing is added to the cache. (The
+  `dvc status` command will report that the file is `not in cache`.) This is
   analogous to using `git add` before `git commit`. Use `dvc commit` when ready
   to commit the results to cache.
 
-  > The `dvc status` command will mention that the file is `not in cache`.
-
 - `-h`, `--help` - prints the usage/help message, and exit.
 
 - `-q`, `--quiet` - do not write anything to standard output. Exit with 0 if no

static/docs/command-reference/metrics/add.md

@@ -31,29 +31,29 @@ get to a specific value, if the file contains multiple metrics. See
 ## Options
 
 - `-t`, `--type` - specify a type of the metric file. Accepted values are:
-  `raw`, `json`, `tsv`, `htsv`, `csv`, `hcsv`. Type will be used to determine
-  how `dvc metrics show` handles displaying it. This type will be saved into the
-  corresponding DVC-file and will be used automatically in the
-  `dvc metrics show`. `htsv`/`hcsv` are the same `tsv`/`csv` but the values in
-  the first row of the file will be used as the field names and should be used
-  to address columns in the `--xpath` option. `raw` means that no additional
-  parsing is applied, and `--xpath` is ignored. `raw` is the same as default
-  when no type is provided.
+  `raw`, `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the
+  corresponding DVC-file, and used by `dvc metrics show` to determine how to
+  handle displaying metrics.
+
+  `raw` is the default when no type is provided. It means that no additional
+  parsing is applied, and `--xpath` is ignored. `htsv`/`hcsv` are the same as
+  `tsv`/`csv`, but the values in the first row of the file will be used as the
+  field names and should be used to address columns in the `--xpath` option.
 
 - `-x`, `--xpath` - specify a path within a metric file to get a specific metric
   value. Should be used if the metric file contains multiple numbers and you
-  need to get a only one of them. Only a single path is allowed. This path will
-  be saved into the corresponding DVC-file and will be used automatically in
-  `dvc metrics show`. The accepted value depends on the metric file type
-  (`--type` option):
+  need to get a only one of them. Only a single path is allowed. It will be
+  saved into the corresponding DVC-file, and used by `dvc metrics show` to
+  determine how to handle displaying metrics. The accepted value depends on the
+  metric file type (`--type` option):
 
-  - `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or
+  - For `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or
     [jsonpath-ng](https://github.com/h2non/jsonpath-ng) for available options.
     For example, `"AUC"` extracts the value from the following JSON-formatted
     metric file: `{"AUC": "0.624652"}`.
-  - `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based.
-  - `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based. First
-    row is used to specify column names and is not included into index.
+  - For `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based.
+  - For `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based.
+    First row is used to specify column names and is not included into index.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

static/docs/command-reference/metrics/modify.md

@@ -34,29 +34,29 @@ ERROR: failed to modify metric file settings -
 ## Options
 
 - `-t`, `--type` - specify a type of the metric file. Accepted values are:
-  `raw`, `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be used to determine how
-  `dvc metrics show` handles displaying it. This type will be saved into the
-  corresponding DVC-file and will be used automatically in the
-  `dvc metrics show`. `htsv` and `hcsv` are `tsv` and `csv` but the values in
-  the first row of the file will be used as the field names and can be used to
-  address columns in the `--xpath` option. `raw` means that no additional
-  parsing is applied, and `--xpath` is ignored. `raw` is the same as default
-  when no type is provided.
+  `raw`, `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the
+  corresponding DVC-file, and used by `dvc metrics show` to determine how to
+  handle displaying metrics.
+
+  `raw` is the default when no type is provided. It means that no additional
+  parsing is applied, and `--xpath` is ignored. `htsv`/`hcsv` are the same as
+  `tsv`/`csv`, but the values in the first row of the file will be used as the
+  field names and should be used to address columns in the `--xpath` option.
 
 - `-x`, `--xpath` - specify a path within a metric file to get a specific metric
   value. Should be used if the metric file contains multiple numbers and you
-  need to get a only one of them. Only a single path is allowed. This path will
-  be saved into the corresponding DVC-file and will be used automatically in
-  `dvc metrics show`. The accepted value depends on the metric file type
-  (`--type` option):
+  need to get a only one of them. Only a single path is allowed. It will be
+  saved into the corresponding DVC-file, and used by `dvc metrics show` to
+  determine how to handle displaying metrics. The accepted value depends on the
+  metric file type (`--type` option):
 
-  - `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or
+  - For `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or
     [jsonpath-ng](https://github.com/h2non/jsonpath-ng) for available options.
     For example, `"AUC"` extracts the value from the following JSON-formatted
     metric file: `{"AUC": "0.624652"}`.
-  - `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based.
-  - `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based. First
-    row is used to specify column names and is not included into index.
+  - For `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based.
+  - For `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based.
+    First row is used to specify column names and is not included into index.
 
 - `-h`, `--help` - prints the usage/help message, and exit.
 

static/docs/command-reference/metrics/remove.md

@@ -31,6 +31,15 @@ ERROR: failed to remove metric file '<path>' -
        unable to find DVC-file with output '<path>'
 ```
 
+## Options
+
+- `-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.
+
 ## Examples
 
 Let's first create a dummy non-cached metric <abbr>output</abbr> with the `-M`

static/docs/command-reference/metrics/show.md

@@ -41,40 +41,46 @@ extension.)
 
 ## Options
 
-- `-t`, `--type` - specify a type of the metric file that will be used to
-  determine how to handle `xpath` parameter from down below. Accepted values
-  are: `raw`, `json`, `tsv`, `htsv`, `csv`, `hcsv`. If this parameter is not
+- `-t`, `--type` - specify a type of the metric file. Accepted values are:
+  `raw`, `json`, `tsv`, `htsv`, `csv`, `hcsv`. It will be saved into the
+  corresponding DVC-file, and used by `dvc metrics show` to determine how to
+  handle displaying metrics.
+
+  `raw` is the default when no type is provided. It means that no additional
+  parsing is applied, and `--xpath` is ignored. `htsv`/`hcsv` are the same as
+  `tsv`/`csv`, but the values in the first row of the file will be used as the
+  field names and should be used to address columns in the `--xpath` option.
+
+  This option along with `--xpath` below takes precedence over the `type` and
+  `xpath` specified in the corresponding DVC file. If this parameter is not
   given, the type can be detected by the file extension automatically if the
-  type is supported. If any other value is specified it is ignored and `type` is
-  defaulted to `raw`. `htsv`/`hcsv` are the same `tsv`/`csv` but the values in
-  the first row of the file will be used as the field names and should be used
-  to address columns in the `--xpath` option. `raw` means that no additional
-  parsing is applied, and `--xpath` is ignored. `raw` is the same as default
-  when no type is provided. This option along with `--xpath` below takes
-  precedence over the `type` and `xpath` specified in the corresponding DVC
-  file.
+  type is supported. If any other value is specified, it is ignored and
+  defaulted back to `raw`.
 
 - `-x`, `--xpath` - specify a path within a metric file to get a specific metric
   value. Should be used if the metric file contains multiple numbers and you
-  need to get a only one of them. Only a single path is allowed. If multiple
-  metric files exist in the <abbr>project</abbr>, the same parser and path will
-  be applied to all of them. If `xpath` for a particular metric has been set
-  using `dvc metrics modify`, the path passed with this option will overwrite it
-  for the current command run only – It may fail to produce any results or parse
-  files that are not in a corresponding format in this case. The Accepted value
-  depends on the metric file type (`--type` option):
-
-  - `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or
+  need to get a only one of them. Only a single path is allowed. It will be
+  saved into the corresponding DVC-file, and used by `dvc metrics show` to
+  determine how to handle displaying metrics. The accepted value depends on the
+  metric file type (`--type` option):
+
+  - For `json` - see [JSONPath spec](https://goessner.net/articles/JsonPath/) or
     [jsonpath-ng](https://github.com/h2non/jsonpath-ng) for available options.
-    For example, `"AUC"` extracts the value from the following json-formatted
+    For example, `"AUC"` extracts the value from the following JSON-formatted
     metric file: `{"AUC": "0.624652"}`. You can also filter on certain values,
     for example `"$.metrics[?(@.deviation_mse<0.30) & (@.value_mse>0.4)]"`
     extracts only the values for model versions if they meet the given
     conditions from the metric file:
     `{"metrics": [{"dataset": "train", "deviation_mse": 0.173461, "value_mse": 0.421601}]}`
-  - `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based.
-  - `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based. First
-    row is used to specify column names and is not included into index.
+  - For `tsv`/`csv` - `row,column` e.g. `1,2`. Indices are 0-based.
+  - For `htsv`/`hcsv` - `row,column name` e.g. `0,Name`. Row index is 0-based.
+    First row is used to specify column names and is not included into index.
+
+  If multiple metric files exist in the <abbr>project</abbr>, the same parser
+  and path will be applied to all of them. If `xpath` for a particular metric
+  has been set using `dvc metrics modify`, the path passed with this option will
+  overwrite it for the current command run only – It may fail to produce any
+  results or parse files that are not in a corresponding format in this case.
 
 - `-a`, `--all-branches` - get and print metric file contents across all Git
   branches. It can be used to compare different variants of an experiment.

static/docs/command-reference/remote/add.md

@@ -76,6 +76,13 @@ Use `dvc config` to unset/change the default remote as so:
 
 - `-f`, `--force` - overwrite existing remote with new `url` value.
 
+- `-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.
+
 ## Examples
 
 The following are the types of remote storage (protocols) supported:

static/docs/command-reference/repro.md

@@ -89,18 +89,20 @@ specified), and updates stage files with the new checksum information.
   present in `DVC` repository.
 
 - `--ignore-build-cache` - in cases like `... -> A (changed) -> B -> C` it will
-  reproduce `A` first and then `B` even if `B` was previously executed with the
-  same inputs from `A` (cached). It might be useful when we have a common
-  dependency among all stages and want to specify it once (for the stage `A`
-  here). For example, if we know that all stages (`A` and below) depend on
-  `requirements.txt`, we can specify it only once in `A`, omitting it in `B` and
-  `C`. To be precise , it reproduces all descendants of a changed stage or the
-  stages following the changed stage, even if their direct dependencies did not
-  change. Like with the same option on `dvc run`, this is a way to force execute
-  stages without changes. This can also be useful for pipelines containing
-  stages that produce non-deterministic (semi-random) outputs. For
-  non-deterministic stages the outputs can vary on each execution, meaning the
-  cache cannot be trusted for such stages.
+  reproduce `A` first and then `B`, even if `B` was previously executed with the
+  same inputs from `A` (cached). To be precise, it reproduces all descendants of
+  a changed stage or the stages following the changed stage, even if their
+  direct dependencies did not change.
+
+  It can be useful when we have a common dependency among all stages, and want
+  to specify it only once (for stage `A` here). For example, if we know that all
+  stages (`A` and below) depend on `requirements.txt`, we can specify it in `A`,
+  and omit it in `B` and `C`.
+
+  Like with the same option on `dvc run`, this is a way to force-execute stages
+  without changes. This can also be useful for pipelines containing stages that
+  produce non-deterministic (semi-random) outputs, where outputs can vary on
+  each execution, meaning the cache cannot be trusted for such stages.
 
 - `--downstream` - only execute the stages after the given `targets` in their
   corresponding pipelines, including the target stages themselves.

static/docs/command-reference/run.md

@@ -135,12 +135,10 @@ try creating a pipeline.
   default and deprecated. See `dvc remove` as well for more details.
 
 - `--no-commit` - do not save outputs to cache. A DVC-file is created, and an
-  entry is added to `.dvc/state`, while nothing is added to the cache. Useful
-  when running different experiments and you don't want to fill up your cache
-  with temporary files. Use `dvc commit` when ready to commit the results to
-  cache.
-
-  > The `dvc status` command will mention that the file is `not in cache`.
+  entry is added to `.dvc/state`, while nothing is added to the cache. (The
+  `dvc status` command will report that the file is `not in cache`.) Useful when
+  running different experiments and you don't want to fill up your cache with
+  temporary files. Use `dvc commit` when ready to commit the results to cache.
 
 - `--always-changed` - always consider this DVC-file as changed. As a result
   `dvc status` will report it as `always changed` and `dvc repro` will always

static/docs/user-guide/contributing/core.md

@@ -275,7 +275,7 @@ $ ./scripts/ci/remove_hadoop.sh
 
 </details>
 
-## Code style guidelines (for Python)
+## Code style guidelines (Python)
 
 We are using [PEP8](https://www.python.org/dev/peps/pep-0008/?) and checking
 that our code is formatted with [black](https://github.com/ambv/black).

static/docs/user-guide/contributing/docs.md

@@ -82,7 +82,7 @@ If you intend to change JavaScript (Node) files, test the changes with
 `yarn format-staged` and `yarn lint`. (All of these checks will be enforced
 automatically upon [submitting PRs](#submitting-changes).)
 
-## Doc style guidelines and tips (for JavaScript and Markdown)
+## Doc style guidelines (JavaScript and Markdown)
 
 The first few of the rules below should be enforced automatically by a Git
 pre-commit hook that is integrated when `yarn` installs the project dependencies
@@ -104,17 +104,16 @@ pre-commit hook that is integrated when `yarn` installs the project dependencies
   `yarn prettier --write '{static,src}/**/*.{js,jsx,md}'` formats all the
   JavaScript and Markdown files.
 
-- Using `dvc <command>` in the Markdown files, the docs engine will create a
-  link to that command automatically. (No need to use `[]()` explicitly to
-  create them.)
+- Markdown: Using `dvc <command>`, the docs engine will create a link to that
+  command automatically. (No need to use `[]()` explicitly to create them.)
 
-- Neither bullet lists nor each bullet's text should be too long (3 sentence
+- Markdown: Neither bullet lists nor each item's should be too long (3 sentence
   paragraphs max.) Full sentence bullets should begin with a capital letter and
   end in period `.` otherwise they can be all lower case and have no ending
-  punctuation. Bullets can be separated by an empty line if they contain short
-  paragraphs.
+  punctuation. Bullets can be separated by an empty line if they contain several
+  paragraphs, but this is discouraged, to keep each item short.
 
-- Syntax highlighting in fenced code blocks (Markdown) should use the `usage`
+- Markdown: Syntax highlighting in fenced code blocks should use the `usage`
   `dvc`, and `yaml` custom languages. `usage` is employed to show the
   `dvc --help` output for each command reference. `dvc` can be used to show
   examples of commands and their output in a terminal session. `yaml` is used to