Command short_help is ignored

[aazuspan]

Hi @ewels, I came across another discrepancy between click and rich-click that's giving me a little trouble: how command short help is handled.

click generates short help from the first sentence of the command's help unless short_help is explicitly passed to the command, in which case that will be used. rich-click seems to use the first paragraph instead, and you can't overwrite it using short_help.

Here's a minimum reproducible example using rich-click==1.2.0.

@click.group()
def foo():
    """
    Help for group.
    """
    pass

@foo.command()
def command():
    """
    Help for command. This sentence shouldn't be included in the short help.
    """
    pass

@foo.command(short_help="This won't be used by rich-click")
def command2():
    """
    This should be overwritten by the explicitly passed short-help.
    """
    pass

Output of foo --help using click:

And using rich-click:

Thanks again for making rich-click!

[ewels]

Thanks for reporting this - I noticed the short_help argument out of the corner of my eye a little while ago and meant to check to see if it was used but then forgot about it. We should definitely use that if supplied 👍🏻

Regarding the second bit about truncating after the first sentence (.). This was a mostly deliberate choice, as generally the wider terminal output and nicer formatting should allow longer strings for rich-click than for native click. I can see how the change in behaviour could cause issues though. I'm inclined to say that we either do nothing about this, or add a new option to take the option/arg short text from the click functions (so truncating exactly as with native). What do you think?

[aazuspan]

Yeah, defaulting to longer help strings seems totally reasonable with the improved readability from rich-click. Having a config option to preserve native click truncating might be nice if someone really needs identical behavior, but as long as you can manually override the automatic truncation using short_help, it doesn't seem like a big deal to me.

[ewels]

Ok, short_help should now be supported (in an almost suspiciously small amount of additional code..)

[ewels]

Ok, and added a USE_CLICK_SHORT_HELP global which uses the default click handling for commands. Setting this to True will then do the stuff with the first sentence and adding ellipses etc. as with vanilla click.

Thanks for reporting!

[aazuspan]

Works perfectly. Thanks again @ewels!

[ewels]

Published in v1.2.1 https://pypi.org/project/rich-click/1.2.1/