Click: Add newlines between options in help text

[chaoflow]

In case of multi-line help messages for options the list of options cmd --help gets difficult to read. It would be great to have an option to toggle extra newlines after multi-line help messages / in general between option help messages.

[pwlandoll]

@chaoflow , what kind of setting would this look like? I poked around to see where it might work best, I'm thinking something like this:

# Add one newline after every option:
@click.command(context_settings=dict(help_newline_padding_size=1, help_newline_padding_style='all'))
# Or, add two newlines after each multi-line option
@click.command(context_settings=dict(help_newline_padding_size=2, help_newline_padding_style='multiline'))

Is this something that the maintainers would consider adding? If so, I think this implementation could be a good start.

[davidism]

I don't want this to be an option. If you think it's more readable, just implement it as standard.

[pwlandoll]

This seems to get the job done:

diff --git a/click/formatting.py b/click/formatting.py
index a3d6a4d..a8de859 100644
--- a/click/formatting.py
+++ b/click/formatting.py
@@ -200,10 +200,13 @@ class HelpFormatter(object):
             text_width = max(self.width - first_col - 2, 10)
             lines = iter(wrap_text(second, text_width).splitlines())
             if lines:
+                padding = ''
                 self.write(next(lines) + '\n')
                 for line in lines:
+                    padding = '\n'
                     self.write('%*s%s\n' % (
                         first_col + self.current_indent, '', line))
+                self.write(padding)
             else:
                 self.write('\n')
 ```
e: I modified the sample hello.py with a longer help message to show this at work:

Options:
--count INTEGER Number of greetings.
--name TEXT The person to greet. I made this help text quite long to
show that adding padding to the help message leaves this
alone.

--help Show this message and exit.
```
I could clean this up and open a pull request with some tests? (Interestingly, this change did not break any existing tests.)

[mcclure]

I have an opinion: I think the spaces between options looks good, but I think that if there are options between some of the options, there should be blank lines between all of the options. It seems visually confusing to me for it to be inconsistent.

[pwlandoll]

I haven't looked at this for a while, I'd almost forgotten about it.

I would agree that it should be all or nothing, but should that extra spacing apply only when there are help messages that wrap, or no matter what?

[davidism]

I'd say only when any wrap.

[mcclure]

I think if I were deciding the rule, there would be no-spaces if no option messages wrap, and spaces for all options if at least one option wraps.

Maybe there also should be an override because I can imagine a situation where there's like, 20 options, and only one wraps, and in that case maybe it's actually better to leave the newlines out, but you couldn't really predict that ahead of time without a human looking at it and making a judgement.

[pwlandoll]

Cool, I'll play around and see which ones look the best. Thanks @davidism and @mcclure!

[psss]

Adding extra new lines only for some options looks to me quite inconsistent and can be very confusing. Here's a real-life example from my project:

-i, --id ID                  Run id (name or directory path).
-l, --last                   Execute the last run once again.
-a, --all                    Run all steps, customize some.
-u, --until STEP             Enable given step and all preceding steps.
-s, --since STEP             Enable given step and all following steps.
-A, --after STEP             Enable all steps before the given one.
-B, --before STEP            Enable all steps after the given one.
-S, --skip STEP              Skip given step(s) during test run execution.
-e, --environment KEY=VALUE  Set environment variable. Can be specified
                             multiple times.

-v, --verbose                Show more details. Use multiple times to raise
                             verbosity.

-d, --debug                  Provide debugging information. Repeat to see
                             more details.

-q, --quiet                  Be quiet. Exit code is just enough for me.
-f, --force                  Overwrite existing files and step data.
-n, --dry                    Run in dry mode. No changes, please.
--help                       Show this message and exit.

This creates an impression of multiple sections but very poorly organized (especially as verbose, debug and quiet belong together but are artificially separated).

If the extra empty line is added, it should be probably added to all options to get a consistent look. But then you get so much space wasted. I'd say that the previous behaviour was much better.

If it's really needed, what about making this feature configurable? It could be something like separate=[True|False|Auto]. What do you think?

[davidism]

No, I do not plan to add configuration options for things like this at this time. There are way, way, way too many opinions about exactly how different things should look and function, and adding options for all of them becomes way too complex. The general philosophy of Click is to makes decisions where it can rather than providing configuration for everything, although there is a general desire to refactor the formatting system to allow projects to override these sorts of things without having to add options for everything in #561.