autodoc params wrap poorly in --help and helptext is duplicated

[BlinkyStitt]

#234 will improve autodocs, but there are more issues.

Right now all of my parameters have their help defined twice. Once in click's decorator for use with --help and once in the docstring for use with autodoc.

For example:

@click.option('bread'):
@click.option('--heat', default=5, help='how much to burn your toast')
@click.option('--slices', default=1, help='the number of slices to toast')
def toast(bread, heat, slices):
    """Make some toast.

    :param int heat: how much to burn your toast
    :param int slices: the number of slices to toast

    .. WARNING::

        This also wraps poorly if it ends up going to multiple lines.
        It puts 4 spaces into the middle of the message

    Here is an example::

        \b
        toast pumpernickle 4
        toast sourdough
    """
    print 'toasting {} slice(s) of {} at heat level {}'.format(slices, bread, heat)

When you do --help with a function like this, the :param: lines get wrapped. I tried just adding a /b above them which fixes --help but the generated docs break with that and it seems silly to have to put a new line between every one.

Also, without the /b in the example, those lines wrap. However, with the /b there is a blank line at the start of all the autodoc codeblocks.

What would be wonderful is if this worked:

@click.option('bread'):
@click.option('--heat', default=5, help='how much to burn your toast')
@click.option('--slices', default=1, help='the number of slices to toast')
def toast(bread, heat, slices):
    """Toast some bread.

    Example::

        toast pumpernickle 4
        toast sourdough
    """
    print 'toasting {} slice(s) of {} at heat level {}'.format(slices, bread, heat)

The above works great with --help right now, but autodoc doesn't have any of the parameter help in it and the example is wrapper.

Any ideas how to make --help and autodoc play nice?

[drakeguan]

Wondering if there is any plan to help reduce the repeated help, one in function's docstring (with sphinx autodoc) and the other in --help form?

[timcera]

This is a me too!

Used baker, then mando for my command line helper libraries, both parse the docstring to display help. This is really nice. I was surprised by click having the argument and option help defined twice.

I started to dig into the code, and there are several ways to do this and wondered which would be the most likely to be accepted.

1. New keyword.
   @click.option('--statistic', helpfromdocstring=True)
2. New decorator.
   @click.option_docstring('--statistic')
3. New helper function. Don't know how to get the name of the argument/option into the helper function.
   @click.option('--statistic', help=click.help_from_docstring)
4. New command decorator where everything is taken from the docstring similar to docopt, baker, and mando.
   @click.command_from_docstring()

Kindest regards,
Tim

[elnuno]

Just a tip for those who face duplicated/redundant text showing up in command help: you can override Command.format_help_text and trim the docstring to your heart's content. I use Args:, but most could use :param as the cutoff point.

    def format_help_text(self, ctx, formatter):
        if self.help:
            args = 'Args:'
            help = self.help
            if args in help:
                help = help[:help.index(args)]  # Remove autodoc stuff
            formatter.write_paragraph()
            with formatter.indentation():
                formatter.write_text(help)

[fdavis]

It looks like we have two outcomes from this issue

1. we should fix this formatting bug defined above
2. we should document Command.format_help_text example above

[davidism]

I think this is more appropriately handled by an extension like sphinx-click. This may become possible as we think about how to rewrite the format system (#561).