Command panels don't support multi-line strings

[apcamargo]

I'm used to write down the description of commands within """ because they can get long. However, it seems that rich-click can't render multi-line strings within the panels. Only the first line is shown.

Multi-line:

@cli.command(context_settings=CONTEXT_SETTINGS)
@click.argument("input", type=click.Path(exists=True))
@click.argument("output", type=click.Path())
@click.option(
    "--threads",
    "-t",
    default=multiprocessing.cpu_count(),
    show_default=True,
    help="Number of threads to use",
)
def test_command(input, output, threads):
    """
    Let's build an almighty mountain. Maybe, just to play a little, we'll put a
    little tree here. Look around, look at what we have. Beauty is everywhere,
    you only have to look to see it. The only prerequisite is that it makes you
    happy. If it makes you happy then it's good. We don't have to be concerned
    about it. We just have to let it fall where it will. By now you should be
    quite happy about what's happening here.
    """

╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│  test-command  Let's build an almighty mountain. Maybe, just to play a little, we'll put a       │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

This is fixed when I put the text in a single line:

@cli.command(context_settings=CONTEXT_SETTINGS)
@click.argument("input", type=click.Path(exists=True))
@click.argument("output", type=click.Path())
@click.option(
    "--threads",
    "-t",
    default=multiprocessing.cpu_count(),
    show_default=True,
    help="Number of threads to use",
)
def test_command(input, output, threads):
    """
    Let's build an almighty mountain. Maybe, just to play a little, we'll put a little tree here. Look around, look at what we have. Beauty is everywhere, you only have to look to see it. The only prerequisite is that it makes you happy. If it makes you happy then it's good. We don't have to be concerned about it. We just have to let it fall where it will. By now you should be quite happy about what's happening here.
    """

╭─ Commands ───────────────────────────────────────────────────────────────────────────────────────╮
│  test-command  Let's build an almighty mountain. Maybe, just to play a little, we'll put a       │
│                little tree here. Look around, look at what we have. Beauty is everywhere, you    │
│                only have to look to see it. The only prerequisite is that it makes you happy.    │
│                If it makes you happy then it's good. We don't have to be concerned about it. We  │
│                just have to let it fall where it will. By now you should be quite happy about    │
│                what's happening here.                                                            │
╰──────────────────────────────────────────────────────────────────────────────────────────────────╯

[ewels]

Thanks for reporting! Does this work as you'd expect with vanilla click output?

[apcamargo]

Vanilla click doesn't allow command descriptions to be rendered over multiple lines, but it does support multi-line strings that use """.

Because the command descriptions are limited to a single line, click tries to be smart and only displays the text that comes before the first period:

def test_command(input, output, threads):
    """
    Let's build an almighty mountain. Maybe, just to play a little, we'll put a
    little tree here. Look around, look at what we have. Beauty is everywhere,
    you only have to look to see it. The only prerequisite is that it makes you
    happy. If it makes you happy then it's good. We don't have to be concerned
    about it. We just have to let it fall where it will. By now you should be
    quite happy about what's happening here.
    """

Commands:
  test-command  Let's build an almighty mountain.

If there's no period before the maximum width of the help dialog, it will use ellipsis:

def test_command(input, output, threads):
    """
    Let's build an almighty mountain Maybe, just to play a little, we'll put a
    little tree here. Look around, look at what we have. Beauty is everywhere,
    you only have to look to see it. The only prerequisite is that it makes you
    happy. If it makes you happy then it's good. We don't have to be concerned
    about it. We just have to let it fall where it will. By now you should be
    quite happy about what's happening here.
    """

Commands:
  test-command  Let's build an almighty mountain Maybe, just to play a...

My preference is the way rich-click renders when you use a single-line string (that is, shows the full description in the dialogue). If the goal is to stay as close to vanilla as possible, I think using ellipsis is fine (although I would use the true ellipsis character to save characters: …).

[ewels]

Thanks 🙏🏻 I think displaying the full text is better too (might be scope for a config option there though I guess 🤔).

I'll take a look into fixing this ASAP.

[ewels]

Ok, this should now be fixed. I think that the previous behaviour of only printing the first line was there because I was trying to mimic the click behaviour of showing a short help text for groups but then having longer help text when doing help on that specific subcommand.

Now it's slightly smarter and takes the first paragraph, according to double newlines. Single newlines are stripped (unless using Markdown, but then they're ignored).