Support truncating help text (by ignoring it)

[kratsg]

Click has the following option: https://click.palletsprojects.com/en/7.x/documentation/?highlight=docstring#truncating-help-texts

@click.command()
@click.pass_context
def cli(ctx):
    """First paragraph.

    This is a very long second
    paragraph and not correctly
    wrapped but it will be rewrapped.
    \f

    :param click.core.Context ctx: Click context.
    """

with the CLI output

$ cli --help
Usage: cli [OPTIONS]

  First paragraph.

  This is a very long second paragraph and not correctly wrapped but it will
  be rewrapped.

Options:
  --help  Show this message and exit.

however, it turns out that the sphinx-click contrib will also show the same help output, instead of using the full docstring. It's clear that this was geared towards being used with sphinx.

[jgallowa07]

Hello! @stephenfin I would love if the sphix generated docs ignored the truncation! it allows you to write nice rst formatted comments inside the cli docstrings, while keeping the command line --help clean. Any progress here?

[stephenfin]

@jgallowa07 Not on my end. Happy to work with someone on PR for this but this isn't high priority for me, unfortunately

[stephenfin]

If anyone does work on this, note that click truncates the provided help string and doesn't seem to record the original version anywhere, as seen here. I don't think this feature will be easily achieved without changes to click itself (to record the raw help string)

[stephenfin]

This is now fixed by using click>=8.1.0, no changes needed for sphinx-click.

[jgallowa07]

@stephenfin This is so amazing! Thank you!