format commands normalize format -> remove short_help option

click/core.py

@@ -9,7 +9,7 @@
 from .utils import make_str, make_default_short_help, echo, get_os_args
 from .exceptions import ClickException, UsageError, BadParameter, Abort, \
      MissingParameter
-from .termui import prompt, confirm
+from .termui import prompt, confirm, get_terminal_size
 from .formatting import HelpFormatter, join_options
 from .parser import OptionParser, split_opt
 from .globals import push_context, pop_context
@@ -746,8 +746,7 @@ class Command(BaseCommand):
     :param help: the help string to use for this command.
     :param epilog: like the help string but it's printed at the end of the
                    help page after everything else.
-    :param short_help: the short help to use for this command.  This is
-                       shown on the command listing of the parent command.
+    :param short_help: deprecated in favor of help
     :param add_help_option: by default each command registers a ``--help``
                             option.  This can be disabled by this parameter.
     :param hidden: hide this command from help outputs.
@@ -765,12 +764,9 @@ def __init__(self, name, context_settings=None, callback=None,
         #: should show up in the help page and execute.  Eager parameters
         #: will automatically be handled before non eager ones.
         self.params = params or []
-        self.help = help
+        self.help = help or short_help
         self.epilog = epilog
         self.options_metavar = options_metavar
-        if short_help is None and help:
-            short_help = make_default_short_help(help)
-        self.short_help = short_help
         self.add_help_option = add_help_option
         self.hidden = hidden
 
@@ -1007,16 +1003,30 @@ def format_commands(self, ctx, formatter):
         after the options.
         """
         rows = []
-        for subcommand in self.list_commands(ctx):
-            cmd = self.get_command(ctx, subcommand)
-            # What is this, the tool lied about a command.  Ignore it
-            if cmd is None:
-                continue
-            if cmd.hidden:
-                continue
-
-            help = cmd.short_help or ''
-            rows.append((subcommand, help))
+        # Ignore errant none case and hidden commands
+        commands = [self.get_command(ctx, cmd) for cmd in self.list_commands(ctx)
+                    if cmd is not None]
+        commands = [cmd for cmd in commands if not cmd.hidden]
+        if len(commands) > 0:
+            name_length = lambda c: len(c.name)
+            # formater adds wraps additional spaces
+            command_names_width = max(map(name_length,commands)) + 4
+            ctx_width = ctx.max_content_width or ctx.terminal_width
+            if ctx_width is not None:
+                max_width = min(ctx_width, get_terminal_size()[0])
+            else:
+                max_width = get_terminal_size()[0]
+            # add space to allow for truncating word with elipse
+            max_width = max_width - command_names_width - 6
+            for subcommand in commands:
+                if subcommand.help is None:
+                    help = ''
+                else:
+                    if len(subcommand.help) < max_width:
+                        help = subcommand.help
+                    else:
+                        help = make_default_short_help(subcommand.help, max_width)
+                rows.append((subcommand.name, help))
 
         if rows:
             with formatter.section('Commands'):

docs/documentation.rst

@@ -103,34 +103,6 @@ Example:
     invoke(hello, args=['--help'])
 
 
-Command Short Help
-------------------
-
-For commands, a short help snippet is generated.  By default, it's the first
-sentence of the help message of the command, unless it's too long.  This can
-also be overridden:
-
-.. click:example::
-
-    @click.group()
-    def cli():
-        """A simple command line tool."""
-
-    @cli.command('init', short_help='init the repo')
-    def init():
-        """Initializes the repository."""
-
-    @cli.command('delete', short_help='delete the repo')
-    def delete():
-        """Deletes the repository."""
-
-And what it looks like:
-
-.. click:run::
-
-    invoke(cli, prog_name='repo.py')
-
-
 Help Parameter Customization
 ----------------------------
 

examples/complex/complex/commands/cmd_init.py

@@ -2,7 +2,7 @@
 from complex.cli import pass_context
 
 
-@click.command('init', short_help='Initializes a repo.')
+@click.command('init', help='Initializes a repo.')
 @click.argument('path', required=False, type=click.Path(resolve_path=True))
 @pass_context
 def cli(ctx, path):

examples/complex/complex/commands/cmd_long.py

@@ -0,0 +1,10 @@
+import click
+from complex.cli import pass_context
+
+
+@click.command('long', context_settings={'max_content_width': 700}, help='Shows a realy long message meant for the purposes of debugging the short help default option shortener function in util'*20)
+@pass_context
+def cli(ctx):
+    """Shows file changes in the current working directory."""
+    ctx.log('long: stuff happened')
+    ctx.vlog('bla bla bla, volatile long long long long long long unsigned debug info')

examples/complex/complex/commands/cmd_status.py

@@ -2,7 +2,7 @@
 from complex.cli import pass_context
 
 
-@click.command('status', short_help='Shows file changes.')
+@click.command('status', help='Shows file changes.')
 @pass_context
 def cli(ctx):
     """Shows file changes in the current working directory."""

examples/repo/repo.py

@@ -137,7 +137,7 @@ def commit(repo, files, message):
     click.echo('Commit message:\n' + msg)
 
 
-@cli.command(short_help='Copies files.')
+@cli.command(help='Copies files.')
 @click.option('--force', is_flag=True,
               help='forcibly copy over an existing managed file')
 @click.argument('src', nargs=-1, type=click.Path())

tests/test_commands.py

@@ -40,7 +40,7 @@ def dist(ctx, count):
 
 
 def test_auto_shorthelp(runner):
-    @click.group()
+    @click.group(context_settings={'max_content_width': 67})
     def cli():
         pass