Add Option.get_help_spec to extract the help's left part of an hidden option

[kdeldycke]

This PR splits the production of an option's left help column into its own dedicated column. This always returns the invocation specification of an option, even if that option is hidden.

get_help_record() on the other hand is unmodified and still keep returning the whole option's help that is to be displayed.

That distinction help separate the rendering layer:

• get_help_record() is returning what should be displayed to the user
• get_help_spec() is returning what the option specification is, regardless of the decision to display it to the user

This allows finer introspection of the Click machinery and its rendering pipeline.

This is the other half of a work I initiated 2 years ago with:

• Split extra help item computing with help record rendering #2516
• Split generation of help extra items and rendering #2517

[janluke]

This will allow better integration for help-enhancing tools wrapping Click like Cloup (cc @janluke)

Can you explain how this new method help us or how do you plan to use it? We already get (left_col, right_col) from get_help_record.

[kdeldycke]

This will allow better integration for help-enhancing tools wrapping Click like Cloup (cc @janluke)

Can you explain how this new method help us or how do you plan to use it? We already get (left_col, right_col) from get_help_record.

Ah. I apologize. I was a bit quick to invoke you.😅 I just had an old impression that this was something you would rely on but I conflated my use-case and yours. I should have tripled-checked it. 🙇

I need to be more precise: this PR allows me to extract the left_col even when the option is hidden (self.hidden is True). This is the exact application of a workaround I had to introspect all parameters of a CLI, including those who are hidden: https://github.com/kdeldycke/click-extra/blob/68868d4489b87dca8247b2d73fc731167265febe/click_extra/parameters.py#L593-L613

This allows me to print metadata about an option (in this particular case its invocation specifications), outside its help screen context, and so outside the decision of either printing it to the user or not. Because an option hidden from the help screen is still an option recognize by the CLI and still has an effect on it. This is useful to implement deprecated options or preview options you don't want to advertise to the user. Still, you might need to print its specification in deprecation warnings, logs or error messages. That's where this new method can be useful.

In Click Extra I need the option specs to produce machine-readable specs in JSON, Markdown and Carapace, and live introspection rendering of third-party Click CLI.