Skip to content

Commit 14b213a

Browse files
jorgeorpineljorgeorpinel
authored
Specify cmd arg names (metavars), et al. (#3626)
* add: -f arg name from FILE to <filename> to match dvc.org cmd ref * dvc: cmd arg names (metavars) to match docs for #3626 * metrics: update help output to indicate supported types per #3409 and for #3572 * dvc: reorder subcommands to match docs for #3608
1 parent f0c81bc commit 14b213a

File tree

13 files changed

+145
-87
lines changed

13 files changed

+145
-87
lines changed

‎dvc/command/add.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -53,6 +53,7 @@ def add_parser(subparsers, parent_parser):
5353
"-f",
5454
"--file",
5555
help="Specify name of the DVC-file this command will generate.",
56+
metavar="<filename>",
5657
)
5758
parser.add_argument(
5859
"targets", nargs="+", help="Input files/directories to add."

‎dvc/command/data_sync.py

Lines changed: 15 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -89,7 +89,11 @@ def shared_parent_parser():
8989
add_help=False, parents=[get_parent_parser()]
9090
)
9191
shared_parent_parser.add_argument(
92-
"-j", "--jobs", type=int, help="Number of jobs to run simultaneously."
92+
"-j",
93+
"--jobs",
94+
type=int,
95+
help="Number of jobs to run simultaneously.",
96+
metavar="<number>",
9397
)
9498
shared_parent_parser.add_argument(
9599
"targets",
@@ -115,7 +119,7 @@ def add_parser(subparsers, _parent_parser):
115119
formatter_class=argparse.RawDescriptionHelpFormatter,
116120
)
117121
pull_parser.add_argument(
118-
"-r", "--remote", help="Remote repository to pull from."
122+
"-r", "--remote", help="Remote storage to pull from", metavar="<name>",
119123
)
120124
pull_parser.add_argument(
121125
"-a",
@@ -171,7 +175,7 @@ def add_parser(subparsers, _parent_parser):
171175
formatter_class=argparse.RawDescriptionHelpFormatter,
172176
)
173177
push_parser.add_argument(
174-
"-r", "--remote", help="Remote repository to push to."
178+
"-r", "--remote", help="Remote storage to push to", metavar="<name>",
175179
)
176180
push_parser.add_argument(
177181
"-a",
@@ -223,7 +227,10 @@ def add_parser(subparsers, _parent_parser):
223227
formatter_class=argparse.RawDescriptionHelpFormatter,
224228
)
225229
fetch_parser.add_argument(
226-
"-r", "--remote", help="Remote repository to fetch from."
230+
"-r",
231+
"--remote",
232+
help="Remote storage to fetch from",
233+
metavar="<name>",
227234
)
228235
fetch_parser.add_argument(
229236
"-a",
@@ -292,7 +299,10 @@ def add_parser(subparsers, _parent_parser):
292299
help="Show status of a local cache compared to a remote repository.",
293300
)
294301
status_parser.add_argument(
295-
"-r", "--remote", help="Remote repository to compare local cache to."
302+
"-r",
303+
"--remote",
304+
help="Remote storage to compare local cache to",
305+
metavar="<name>",
296306
)
297307
status_parser.add_argument(
298308
"-a",

‎dvc/command/gc.py

Lines changed: 10 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -109,7 +109,10 @@ def add_parser(subparsers, parent_parser):
109109
help="Collect garbage in remote repository.",
110110
)
111111
gc_parser.add_argument(
112-
"-r", "--remote", help="Remote storage to collect garbage in."
112+
"-r",
113+
"--remote",
114+
help="Remote storage to collect garbage in",
115+
metavar="<name>",
113116
)
114117
gc_parser.add_argument(
115118
"-f",
@@ -119,7 +122,11 @@ def add_parser(subparsers, parent_parser):
119122
help="Force garbage collection - automatically agree to all prompts.",
120123
)
121124
gc_parser.add_argument(
122-
"-j", "--jobs", type=int, help="Number of jobs to run simultaneously."
125+
"-j",
126+
"--jobs",
127+
type=int,
128+
help="Number of jobs to run simultaneously.",
129+
metavar="<number>",
123130
)
124131
gc_parser.add_argument(
125132
"-p",
@@ -130,5 +137,6 @@ def add_parser(subparsers, parent_parser):
130137
help="Keep data files required by these projects "
131138
"in addition to the current one. "
132139
"Useful if you share a single cache across repos.",
140+
metavar="<paths>",
133141
)
134142
gc_parser.set_defaults(func=CmdGC)

‎dvc/command/get.py

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -66,10 +66,17 @@ def add_parser(subparsers, parent_parser):
6666
"path", help="Path to a file or directory within the repository"
6767
)
6868
get_parser.add_argument(
69-
"-o", "--out", nargs="?", help="Destination path to download files to"
69+
"-o",
70+
"--out",
71+
nargs="?",
72+
help="Destination path to download files to",
73+
metavar="<path>",
7074
)
7175
get_parser.add_argument(
72-
"--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
76+
"--rev",
77+
nargs="?",
78+
help="Git revision (e.g. SHA, branch, tag)",
79+
metavar="<commit>",
7380
)
7481
get_parser.add_argument(
7582
"--show-url",

‎dvc/command/imp.py

Lines changed: 9 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -48,9 +48,16 @@ def add_parser(subparsers, parent_parser):
4848
"path", help="Path to a file or directory within the repository"
4949
)
5050
import_parser.add_argument(
51-
"-o", "--out", nargs="?", help="Destination path to download files to"
51+
"-o",
52+
"--out",
53+
nargs="?",
54+
help="Destination path to download files to",
55+
metavar="<path>",
5256
)
5357
import_parser.add_argument(
54-
"--rev", nargs="?", help="Git revision (e.g. SHA, branch, tag)"
58+
"--rev",
59+
nargs="?",
60+
help="Git revision (e.g. SHA, branch, tag)",
61+
metavar="<commit>",
5562
)
5663
import_parser.set_defaults(func=CmdImport)

‎dvc/command/imp_url.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -59,6 +59,9 @@ def add_parser(subparsers, parent_parser):
5959
"out", nargs="?", help="Destination path to put files to."
6060
)
6161
import_parser.add_argument(
62-
"-f", "--file", help="Specify name of the DVC-file it generates."
62+
"-f",
63+
"--file",
64+
help="Specify name of the DVC-file this command will generate.",
65+
metavar="<filename>",
6366
)
6467
import_parser.set_defaults(func=CmdImportUrl)

‎dvc/command/ls/__init__.py

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -67,7 +67,10 @@ def add_parser(subparsers, parent_parser):
6767
"--outs-only", action="store_true", help="Show only DVC outputs."
6868
)
6969
list_parser.add_argument(
70-
"--rev", nargs="?", help="Git revision (e.g. branch, tag, SHA)"
70+
"--rev",
71+
nargs="?",
72+
help="Git revision (e.g. SHA, branch, tag)",
73+
metavar="<commit>",
7174
)
7275
list_parser.add_argument(
7376
"path",

‎dvc/command/metrics.py

Lines changed: 52 additions & 49 deletions
Original file line numberDiff line numberDiff line change
@@ -177,6 +177,40 @@ def add_parser(subparsers, parent_parser):
177177

178178
fix_subparsers(metrics_subparsers)
179179

180+
METRICS_ADD_HELP = "Mark a DVC-tracked file as a metric."
181+
metrics_add_parser = metrics_subparsers.add_parser(
182+
"add",
183+
parents=[parent_parser],
184+
description=append_doc_link(METRICS_ADD_HELP, "metrics/add"),
185+
help=METRICS_ADD_HELP,
186+
formatter_class=argparse.RawDescriptionHelpFormatter,
187+
)
188+
metrics_add_parser.add_argument(
189+
"-t", "--type", help="Type of metrics (json/yaml).", metavar="<type>",
190+
)
191+
metrics_add_parser.add_argument(
192+
"-x", "--xpath", help="json/yaml path.", metavar="<path>",
193+
)
194+
metrics_add_parser.add_argument("path", help="Path to a metric file.")
195+
metrics_add_parser.set_defaults(func=CmdMetricsAdd)
196+
197+
METRICS_MODIFY_HELP = "Modify metric default formatting."
198+
metrics_modify_parser = metrics_subparsers.add_parser(
199+
"modify",
200+
parents=[parent_parser],
201+
description=append_doc_link(METRICS_MODIFY_HELP, "metrics/modify"),
202+
help=METRICS_MODIFY_HELP,
203+
formatter_class=argparse.RawDescriptionHelpFormatter,
204+
)
205+
metrics_modify_parser.add_argument(
206+
"-t", "--type", help="Type of metrics (json/yaml).", metavar="<type>",
207+
)
208+
metrics_modify_parser.add_argument(
209+
"-x", "--xpath", help="json/yaml path.", metavar="<path>",
210+
)
211+
metrics_modify_parser.add_argument("path", help="Path to a metric file.")
212+
metrics_modify_parser.set_defaults(func=CmdMetricsModify)
213+
180214
METRICS_SHOW_HELP = "Print metrics, with optional formatting."
181215
metrics_show_parser = metrics_subparsers.add_parser(
182216
"show",
@@ -194,13 +228,14 @@ def add_parser(subparsers, parent_parser):
194228
"-t",
195229
"--type",
196230
help=(
197-
"Type of metrics (json/tsv/htsv/csv/hcsv). "
231+
"Type of metrics (json/yaml). "
198232
"It can be detected by the file extension automatically. "
199233
"Unsupported types will be treated as raw."
200234
),
235+
metavar="<type>",
201236
)
202237
metrics_show_parser.add_argument(
203-
"-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
238+
"-x", "--xpath", help="json/yaml path.", metavar="<path>",
204239
)
205240
metrics_show_parser.add_argument(
206241
"-a",
@@ -234,51 +269,6 @@ def add_parser(subparsers, parent_parser):
234269
)
235270
metrics_show_parser.set_defaults(func=CmdMetricsShow)
236271

237-
METRICS_ADD_HELP = "Mark a DVC-tracked file as a metric."
238-
metrics_add_parser = metrics_subparsers.add_parser(
239-
"add",
240-
parents=[parent_parser],
241-
description=append_doc_link(METRICS_ADD_HELP, "metrics/add"),
242-
help=METRICS_ADD_HELP,
243-
formatter_class=argparse.RawDescriptionHelpFormatter,
244-
)
245-
metrics_add_parser.add_argument(
246-
"-t", "--type", help="Type of metrics (raw/json/tsv/htsv/csv/hcsv)."
247-
)
248-
metrics_add_parser.add_argument(
249-
"-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
250-
)
251-
metrics_add_parser.add_argument("path", help="Path to a metric file.")
252-
metrics_add_parser.set_defaults(func=CmdMetricsAdd)
253-
254-
METRICS_MODIFY_HELP = "Modify metric default formatting."
255-
metrics_modify_parser = metrics_subparsers.add_parser(
256-
"modify",
257-
parents=[parent_parser],
258-
description=append_doc_link(METRICS_MODIFY_HELP, "metrics/modify"),
259-
help=METRICS_MODIFY_HELP,
260-
formatter_class=argparse.RawDescriptionHelpFormatter,
261-
)
262-
metrics_modify_parser.add_argument(
263-
"-t", "--type", help="Type of metrics (raw/json/tsv/htsv/csv/hcsv)."
264-
)
265-
metrics_modify_parser.add_argument(
266-
"-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
267-
)
268-
metrics_modify_parser.add_argument("path", help="Path to a metric file.")
269-
metrics_modify_parser.set_defaults(func=CmdMetricsModify)
270-
271-
METRICS_REMOVE_HELP = "Remove metric mark on a DVC-tracked file."
272-
metrics_remove_parser = metrics_subparsers.add_parser(
273-
"remove",
274-
parents=[parent_parser],
275-
description=append_doc_link(METRICS_REMOVE_HELP, "metrics/remove"),
276-
help=METRICS_REMOVE_HELP,
277-
formatter_class=argparse.RawDescriptionHelpFormatter,
278-
)
279-
metrics_remove_parser.add_argument("path", help="Path to a metric file.")
280-
metrics_remove_parser.set_defaults(func=CmdMetricsRemove)
281-
282272
METRICS_DIFF_HELP = "Show changes in metrics between commits"
283273
" in the DVC repository, or between a commit and the workspace."
284274
metrics_diff_parser = metrics_subparsers.add_parser(
@@ -303,18 +293,20 @@ def add_parser(subparsers, parent_parser):
303293
"Metric files or directories (see -R) to show diff for. "
304294
"Shows diff for all metric files by default."
305295
),
296+
metavar="<paths>",
306297
)
307298
metrics_diff_parser.add_argument(
308299
"-t",
309300
"--type",
310301
help=(
311-
"Type of metrics (json/tsv/htsv/csv/hcsv). "
302+
"Type of metrics (json/yaml). "
312303
"It can be detected by the file extension automatically. "
313304
"Unsupported types will be treated as raw."
314305
),
306+
metavar="<type>",
315307
)
316308
metrics_diff_parser.add_argument(
317-
"-x", "--xpath", help="json/tsv/htsv/csv/hcsv path."
309+
"-x", "--xpath", help="json/yaml path.", metavar="<path>",
318310
)
319311
metrics_diff_parser.add_argument(
320312
"-R",
@@ -333,3 +325,14 @@ def add_parser(subparsers, parent_parser):
333325
help="Show output in JSON format.",
334326
)
335327
metrics_diff_parser.set_defaults(func=CmdMetricsDiff)
328+
329+
METRICS_REMOVE_HELP = "Remove metric mark on a DVC-tracked file."
330+
metrics_remove_parser = metrics_subparsers.add_parser(
331+
"remove",
332+
parents=[parent_parser],
333+
description=append_doc_link(METRICS_REMOVE_HELP, "metrics/remove"),
334+
help=METRICS_REMOVE_HELP,
335+
formatter_class=argparse.RawDescriptionHelpFormatter,
336+
)
337+
metrics_remove_parser.add_argument("path", help="Path to a metric file.")
338+
metrics_remove_parser.set_defaults(func=CmdMetricsRemove)

‎dvc/command/pipeline.py

Lines changed: 10 additions & 10 deletions
Original file line numberDiff line numberDiff line change
@@ -188,6 +188,16 @@ def add_parser(subparsers, parent_parser):
188188

189189
fix_subparsers(pipeline_subparsers)
190190

191+
PIPELINE_LIST_HELP = "List connected groups of stages (pipelines)."
192+
pipeline_list_parser = pipeline_subparsers.add_parser(
193+
"list",
194+
parents=[parent_parser],
195+
description=append_doc_link(PIPELINE_LIST_HELP, "pipeline/list"),
196+
help=PIPELINE_LIST_HELP,
197+
formatter_class=argparse.RawDescriptionHelpFormatter,
198+
)
199+
pipeline_list_parser.set_defaults(func=CmdPipelineList)
200+
191201
PIPELINE_SHOW_HELP = "Show stages in a pipeline."
192202
pipeline_show_parser = pipeline_subparsers.add_parser(
193203
"show",
@@ -243,13 +253,3 @@ def add_parser(subparsers, parent_parser):
243253
"(Finds all DVC-files in the workspace by default.)",
244254
)
245255
pipeline_show_parser.set_defaults(func=CmdPipelineShow)
246-
247-
PIPELINE_LIST_HELP = "List connected groups of stages (pipelines)."
248-
pipeline_list_parser = pipeline_subparsers.add_parser(
249-
"list",
250-
parents=[parent_parser],
251-
description=append_doc_link(PIPELINE_LIST_HELP, "pipeline/list"),
252-
help=PIPELINE_LIST_HELP,
253-
formatter_class=argparse.RawDescriptionHelpFormatter,
254-
)
255-
pipeline_list_parser.set_defaults(func=CmdPipelineList)

‎dvc/command/remote.py

Lines changed: 13 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -167,19 +167,6 @@ def add_parser(subparsers, parent_parser):
167167
)
168168
remote_default_parser.set_defaults(func=CmdRemoteDefault)
169169

170-
REMOTE_REMOVE_HELP = "Remove a data remote."
171-
remote_remove_parser = remote_subparsers.add_parser(
172-
"remove",
173-
parents=[parent_config_parser, parent_parser],
174-
description=append_doc_link(REMOTE_REMOVE_HELP, "remote/remove"),
175-
help=REMOTE_REMOVE_HELP,
176-
formatter_class=argparse.RawDescriptionHelpFormatter,
177-
)
178-
remote_remove_parser.add_argument(
179-
"name", help="Name of the remote to remove."
180-
)
181-
remote_remove_parser.set_defaults(func=CmdRemoteRemove)
182-
183170
REMOTE_MODIFY_HELP = "Modify the configuration of a data remote."
184171
remote_modify_parser = remote_subparsers.add_parser(
185172
"modify",
@@ -213,3 +200,16 @@ def add_parser(subparsers, parent_parser):
213200
formatter_class=argparse.RawDescriptionHelpFormatter,
214201
)
215202
remote_list_parser.set_defaults(func=CmdRemoteList)
203+
204+
REMOTE_REMOVE_HELP = "Remove a data remote."
205+
remote_remove_parser = remote_subparsers.add_parser(
206+
"remove",
207+
parents=[parent_config_parser, parent_parser],
208+
description=append_doc_link(REMOTE_REMOVE_HELP, "remote/remove"),
209+
help=REMOTE_REMOVE_HELP,
210+
formatter_class=argparse.RawDescriptionHelpFormatter,
211+
)
212+
remote_remove_parser.add_argument(
213+
"name", help="Name of the remote to remove."
214+
)
215+
remote_remove_parser.set_defaults(func=CmdRemoteRemove)

‎dvc/command/repro.py

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -92,6 +92,7 @@ def add_parser(subparsers, parent_parser):
9292
"--cwd",
9393
default=os.path.curdir,
9494
help="Directory within your repo to reproduce from.",
95+
metavar="<path>",
9596
)
9697
repro_parser.add_argument(
9798
"-m",

0 commit comments

Comments
 (0)