Fix help with line breaks

[taconi]

Description

Allow tasks to be documented with line breaks.

Motivation behind this PR?

Closes #239.

What type of change is this?

Bug Fix

Checklist

• [X] poe check executed successfully.

Issue

related #239

[nat-n]

Thanks for proposing this change. Looks OK as I explained on #239

What do you think about also making it strip whitespace from the help text around here? https://github.com/nat-n/poethepoet/blob/main/poethepoet/ui.py#L277C50-L277C63

[taconi]

Taking this opportunity, I would like to propose an adjustment for the use of multiple lines. In the example, I had to space it in the help itself to be aligned with the documentation. The idea is for the user to be able to create their documentation without having to add indentation

So with the following task:

[tool.poe.tasks.lint]
cmd = "black --check --diff ."
help = "Run linting tools on the code base"

[tool.poe.tasks.fmt]
cmd = "black -S -l 79 $PATH"
help = """
Use "poe fmt" to format the code.

Examples:
  # Format all files
  poe fmt
"""

The result would already be aligned with the documentation of a single line:

  lint                   Run linting tools on the code base
  fmt                    Use "poe fmt" to format the code.

                         Examples:
                           # Format all files
                           poe fmt

---

Regarding the stip, I would like to see if it would be possible to relocate the default because using strip it would be on the last line of the documentation.

Using that example task:

[tool.poe.tasks.fmt]
cmd = "black -S -l 79 $PATH"
help = """
Use "poe fmt" to format the code.

Examples:
  # Format all files
  poe fmt
"""
[tool.poe.tasks.fmt.args.PATH]
options = ["-p", "--path"]
default = "."
help = """
Change the path that will be formatted.

Examples:
  # Formatting a specific path
  poe fmt -p tests
"""

The result with the strip in the help of this argument would be the following:

    -p, --path           Change the path that will be formatted.

                         Examples:
                           # Formatting a specific path
                           poe fmt -p tests [default: .]

One idea would be to leave [default .] before the documentation:

    -p, --path [default: .] Change the path that will be formatted.

                         Examples:
                           # Formatting a specific path
                           poe fmt -p tests

And maybe leave the help below:

    -p, --path [default: .]
                         Change the path that will be formatted.

                         Examples:
                           # Formatting a specific path
                           poe fmt -p tests

Do you think any of these changes make sense?

[nat-n]

Hey @taconi thanks for this ideas!

Yes I agree that indenting all lines by the amount required to match the column makes sense.

As for repositioning the default. The logic that makes the most sense to me is to keep it at the end, but if the help message is split over multiple lines then the default tag should be preceded by a line break so that it appears on a new line. WDYT?

[taconi]

@nat-n Multi-line behavior applied.

The following task:

[tool.poe.tasks.fmt]
cmd = "black -S -l 79 $PATH"
help = """
Use "poe fmt" to format the code.

Examples:
  # Format all files
  poe fmt
"""
[tool.poe.tasks.fmt.args.PATH]
options = ["-p", "--path"]
default = "."
help = """
Change the path that will be formatted.

Examples:
  # Formatting a specific path
  poe fmt -p tests
"""

Produces the following help output:

Poe the Poet - A task runner that works well with poetry.
version 0.28.0

Result: No task specified.

Usage:
  poe [global options] task [task arguments]

Global options:
  -h, --help            Show this help page and exit
  --version             Print the version and exit
  -v, --verbose         Increase command output (repeatable)
  -q, --quiet           Decrease command output (repeatable)
  -d, --dry-run         Print the task contents but don't actually run it
  -C PATH, --directory PATH
                        Specify where to find the pyproject.toml
  -e EXECUTOR, --executor EXECUTOR
                        Override the default task executor
  --ansi                Force enable ANSI output
  --no-ansi             Force disable ANSI output

Configured tasks:
  fmt                   Use "poe fmt" to format the code.

                        Examples:
                          # Format all files
                          poe fmt
    -p, --path          Change the path that will be formatted.

                        Examples:
                          # Formatting a specific path
                          poe fmt -p tests
    [default: .]

[nat-n]

Nice one!

Although I was thinking the default tag should still be indented in line with the help message, i.e.

   -p, --path          Change the path that will be formatted.

                       Examples:
                         # Formatting a specific path
                         poe fmt -p tests
                       [default: .]

Would you agree?

Also we'll need a test case to cover this behavior, perhaps by extending this one, which uses this fixture.

[nat-n]

Thanks for the contribution @taconi :)