metrics & plots: help output improvements [qa]

[jorgeorpinel]

Please provide information about your setup

DVC 1.0.0a6+283718

Report

λ dvc metrics -h
usage: dvc metrics [-h] [-q | -v] {add,show,diff,remove} ...

Commands to add, manage, collect, and display metrics.
Documentation: <https://man.dvc.org/metrics>

positional arguments:
  {add,show,diff,remove}
                        Use `dvc metrics CMD --help` to display command-specific help.
    add                 Mark a DVC-tracked file as a metric.
    show                Print metrics, with optional formatting.
    diff                Show changes in metrics between commits
    remove              Remove metric mark on a DVC-tracked file.

• remove add and remove
• desc: "Commands to display and compare metrics."
• diff: "Show changes in metrics between commits." (add period: it's a full sentence)

λ dvc metrics show -h
usage: dvc metrics show ...

positional arguments:
  targets             Metric files or directories (see -R) to show

• targets: "Metric files or directories (see -R) to show" Unify metrics behavior with dirs #3935

λ dvc metrics diff -h
usage: dvc metrics diff ...

Show changes in metrics between commits
Documentation: ...

• "Show changes in metrics between commits." (end in period)

---

λ dvc plots -h
usage: dvc plots [-h] [-q | -v] {show,diff} ...

Generating plots for metrics stored in structured files (JSON, CSV, TSV).
Documentation: <https://man.dvc.org/plots>

positional arguments:
  {show,diff}    Use `dvc plots CMD --help` to display command-specific help.
    show         Generate a plots image file from a metrics file.
    diff         Plot differences in metrics between commits in the DVC repository, or between the last commit and the workspace.

• desc: "Commands to visualize and compare plot metrics in structured files (JSON, CSV, TSV)."
• show: "Generate plot from a metrics file."
• diff: "Plot differences in metrics between commits."

λ dvc plots show -h
usage: dvc plots show [-h] [-q | -v] [-t [TEMPLATE]] [-o OUT] [-x X] [-y Y] [--no-csv-header] [--show-json] [--title TITLE] [--xlab XLAB]
                      [--ylab YLAB]
                      [targets [targets ...]]

Generate a plots image file from a metrics file.
Documentation: <https://man.dvc.org/plots/show>

positional arguments:
  targets               Metrics files to visualize. Shows all plots by default.

• desc: "Generate plot from a metrics file."
• targets: why is it printed as optional? The command actually requires it. See plots show: targets are required but help output indicates otherwise [qa] #3925
• option arguments from UPPER_CASE to <type_format>. Probably:
  • TEMPLATE -> <path>
  • OUT -> <path>
  • X/Y -> <field>
  • TITLE -> <text>
  • XLAB/YLAB -> <text>

λ dvc plots diff -h
usage: dvc plots diff [-h] [-q | -v] [-t [TEMPLATE]] [--targets [TARGETS [TARGETS ...]]] [-o OUT] [-x X] [-y Y] [--no-csv-header] [--show-json]
                      [--title TITLE] [--xlab XLAB] [--ylab YLAB]
                      [revisions [revisions ...]]

Plot differences in metrics between commits in the DVC repository, or between the last commit and the workspace.
Documentation: <https://man.dvc.org/plots/diff>

positional arguments:
  revisions             Git commits to plot from

• desc: "Plot differences in metrics between commits."
• option arguments from ... Same as previous command plus:
  • TARGETS -> <path>
• revisions: "Git commits to plot from/to"

Note that all these are already being applied to docs in treeverse/dvc.org/pull/1360 and treeverse/dvc.org/pull/1382

UPDATE: Similar updates apply to plots modify now that it has been added.

---

EXTRA: Additionally it would be nice to reorder the command parameters to match the order in the Options sections of the corresponding published cmd refs.

[jorgeorpinel]

p.s. sorry I don't currently have the capacity to work on this, otherwise I would've sent a PR instead.

[Suor]

NOTE: We also have dvc plots modify now, not sure it should be advertised though as it doesn't have the full functionality yet - no support for multiple plots per plot file. Also, dvc plots add/delete commands are still missing.

[jorgeorpinel]

plots modify is being introduced to docs in treeverse/dvc.org/pull/1382

We are just merging everything when ready at this point, even if we're early compared to the actual core 1.0 release.

[jorgeorpinel]

And yes, similar changes apply to plots modify please! I will update them in the docs PR so whoever does this one can check that one soon to see what the output and options should look like. Thanks