DM-46297: require label to be provided to write-curated-calibrations

[TallJimbo]

Checklist

• ran Jenkins
• added a release note for user-visible changes to doc/changes

[leeskelvin]

The CLI help looks like this now:

$ butler write-curated-calibrations --help
Usage: butler write-curated-calibrations [OPTIONS] REPO INSTRUMENT LAB ...

  Add an instrument's curated calibrations to the data repository.

  REPO is the URI or path to the gen3 repository. Will be created if it does
  not already exist

  The name or fully-qualified class name of an instrument.

  One or more extra strings to include in the collection name (see --label).

I guess LAB has been auto-truncated from LABEL?

I think my main concern here however is that both INSTRUMENT and LAB/LABEL are not specifically named prior to their description. This wasn't so bad when there was only REPO and INSTRUMENT, as REPO is labelled, so it's obvious what the other docstring is referring to. However, now that we've added another, I think it would be helpful to prefix the docstring here with "LABEL is one or more...".

It may be out-of-scope to add "INSTRUMENT is..." on this ticket, but that would probably help with consistency too.

[TallJimbo]

This was actually my first encounter with the mechanism for how the positional argument docs are assembled, which seems to be a workaround for the fact that Click just expects you to put the docs for position arguments into the main usage string yourself. It seems we've been using that workaround incorrectly basically forever, and I think it might have been better to have never invented it (yes, there would then be some duplication, but for docstrings in particular I think it might not be the bad kind of duplication), and given how carefully-considered much of Click is, I bet that's what the design intent (which we've apparently subverted) is.

Ok, enough ranting:

• I'll rename LABEL for the positional arg to LBL; I don't think I can stop the shortening (which is I assume in Click itself) any other way.
• I'll add a LBL: prefix to the sentence about the new positional argument pretty easily.
• Modifying the other positional-argument docstrings would require changes in daf_butler and/or pipe_base, and I don't really want to make more branches for this ticket just for that. I'd prefer to walk back that workaround and have our scripts start documenting their positional arguments as Click intended.

[leeskelvin]

Thanks Jim, that change makes sense to me. I agree it's probably too much to modify daf_butler / pipe_base on this ticket, and I think naming LBL will remove any potential confusion in any case. Thanks also for the DRY link - an interesting read!