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.

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

DOC: Auto-set metavar for parameters with value choices #3326

Merged
merged 6 commits into from Apr 13, 2019

Conversation

@mih
Copy link
Member

@mih mih commented Apr 13, 2019

Old output:

--eval-subdataset-state EVAL_SUBDATASET_STATE

New output:

--eval-subdataset-state {no|commit|full}

This improves the docs of a range of commands, and addresses a comment by @kyleam in #3324

Old output:

`--eval-subdataset-state EVAL_SUBDATASET_STATE`

New output:

`--eval-subdataset-state {'no', 'commit', 'full'}`

This improves the docs of a range of commands.
@codecov
Copy link

@codecov codecov bot commented Apr 13, 2019

Codecov Report

Merging #3326 into master will increase coverage by 45.84%.
The diff coverage is 100%.

Impacted file tree graph

@@             Coverage Diff             @@
##           master    #3326       +/-   ##
===========================================
+ Coverage   45.26%   91.11%   +45.84%     
===========================================
  Files         260      263        +3     
  Lines       34209    34248       +39     
===========================================
+ Hits        15486    31205    +15719     
+ Misses      18723     3043    -15680
Impacted Files Coverage Δ
datalad/plugin/addurls.py 99.68% <ø> (+81.36%) ⬆️
datalad/plugin/wtf.py 82.06% <ø> (+62.78%) ⬆️
datalad/interface/run.py 100% <ø> (+6.15%) ⬆️
datalad/distribution/create_sibling.py 85.09% <ø> (+57.61%) ⬆️
datalad/plugin/check_dates.py 95.83% <ø> (+26.38%) ⬆️
datalad/plugin/add_readme.py 93.1% <100%> (+63.79%) ⬆️
datalad/plugin/export_archive.py 100% <100%> (+75.34%) ⬆️
datalad/interface/base.py 90.09% <100%> (+0.06%) ⬆️
datalad/plugin/export_to_figshare.py 20.71% <100%> (ø) ⬆️
datalad/metadata/extractors/__init__.py 100% <0%> (ø) ⬆️
... and 195 more

Continue to review full report at Codecov.

Legend - Click here to learn more
Δ = absolute <relative> (impact), ø = not affected, ? = missing data
Powered by Codecov. Last update 9ffdca4...8617799. Read the comment docs.

@mih mih added the UX label Apr 13, 2019
kyleam added 5 commits Apr 13, 2019
A nice '{v1|v2|...}' metavar value is now automatically generated. Use
it.
There are some spots where we can't switch to the automatically
generated choice metavar because the constraints are compound rather
than a simple EnsureChoice().  But let's use the same format for
consistency.
When the parameter value is a set of choices that include None, we
define constraints in one of two ways:

  EnsureNone() | EnsureChoice(...)

    or

  EnsureChoice(None, ...)

These behave the same, except that the display in the description is
slightly different and that the choice metavar can now be
automatically generated for the second case.

Switch most spots over to the second form to take advantage of the
automatically generated metavar.  The one spot left unchanged is
sibling's action parameter because showing all the actions rather than
"ACTION" for the metavar seems less clear.
These parameters should be a set of choices but are defined with an
open-ended EnsureStr().  Switch them to EnsureChoice() instead.  Drop
the explicit metavar values because these are now automatically
generated for EnsureChoice() constraints.
@mih
Copy link
Member Author

@mih mih commented Apr 13, 2019

@kyleam Lovely, thx much!

kyleam
kyleam approved these changes Apr 13, 2019
Copy link
Contributor

@kyleam kyleam left a comment

Looks very nice, thanks.

I've pushed some commits to make wider use of this and to make the spots that don't use the automatically generated choice metavar still use a consistent style to format their choice metavar. Feel free to drop any changes you don't agree with.

Copy link
Member

@yarikoptic yarikoptic left a comment

Just an observation (probably not directly related to changes proposed here) - so we have None, "none", and "" used across different commands options to represent "nothing", might be something to unify?

@kyleam
Copy link
Contributor

@kyleam kyleam commented Apr 13, 2019

@mih mih merged commit 7c2c37b into datalad:master Apr 13, 2019
5 checks passed
@mih mih deleted the enh-paramdocs branch Apr 13, 2019
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
Projects
None yet
Linked issues

Successfully merging this pull request may close these issues.

None yet

3 participants