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!