Move short_help contents into docstrings

[iliakur]

What does this PR do?

Motivation

Using short_help is not super idiomatic for click and should be more deliberate.
I'm starting to phase it out in favor of docstrings.

[github-actions]

⚠️ Recommendation: Add qa/skip-qa label

This PR does not modify any files shipped with the agent.

To help streamline the release process, please consider adding the qa/skip-qa label if these changes do not require QA testing.

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 91.16%. Comparing base (7630819) to head (98af7c7).
⚠️ Report is 5 commits behind head on master.

Additional details and impacted files

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[AAraKKe]

Docstrings serve a different purpose than short_help in commands, why not keep the short help in the command and add docstring to add further information? Keeping both? The short_help is shown when doing --help on the parent command and the docstring, if present, are shown when doing --help in the actual command. I am worried that not having the short_help will make someone keep adding information to the docstring and end up having a help when running help on the parent command that is cut with ellipsis because it does not fit. People might just start writing in the docstrings without taking this into account.

I am ok with having the short help as the first line of the docstring, I am not sure if everyone is aware of it. The approach we seem to be following in ddev is to have both to ensure the short version is always available independently of what we have in the docstring. Although not in all commands though, some of them are missing the short_help and create kind of a broken help. This is the output for instance of the ddev dep help where the line of sync is broken.

ddev dep --help
Usage: ddev dep [OPTIONS] COMMAND [ARGS]...

Options:
  -h, --help  Show this message and exit.

Commands:
  freeze   Combine all dependencies for the Agent's static environment.
  pin      Pin a dependency for all checks that require it
  sync     Synchronize integration dependency spec with that of the agent...
  updates  Automatically check for dependency updates

This is an example of how both work together in a run command.

The run command:

#!/usr/bin/env python3
import click

@click.group()
def cli():
    """Main entry point for the example CLI."""
    pass

@cli.command(short_help="Compact help text shown in list.")
def with_short_help():
    """
    This is the full help text for the command.
    
    It is much longer and explains details that you might not want
    to clutter the main help output with.
    
    When you run 'run --help', you will see the 'short_help' text.
    When you run 'run with-short-help --help', you will see this text.
    """
    click.echo("Running command with short_help defined.")

@cli.command()
def without_short_help():
    """
    First line is treated as short help.

    This is the rest of the docstring.
    
    Since 'short_help' is not provided, click uses the first sentence or line
    of the docstring for the listing in the parent command's help.
    """
    click.echo("Running command without short_help defined.")

if __name__ == '__main__':
    cli()

Running help on run

./run --help
Usage: run [OPTIONS] COMMAND [ARGS]...

  Main entry point for the example CLI.

Options:
  --help  Show this message and exit.

Commands:
  with-short-help     Compact help text shown in list.
  without-short-help  First line is treated as short help.

Running the other subcommands

./run with-short-help --help
Usage: run with-short-help [OPTIONS]

  This is the full help text for the command.

  It is much longer and explains details that you might not want to clutter
  the main help output with.

  When you run 'run --help', you will see the 'short_help' text. When you run
  'run with-short-help --help', you will see this text.

Options:
  --help  Show this message and exit.

./run without-short-help --help
Usage: run without-short-help [OPTIONS]

  First line is treated as short help.

  This is the rest of the docstring.

  Since 'short_help' is not provided, click uses the first sentence or line of
  the docstring for the listing in the parent command's help.

Options:
  --help  Show this message and exit.

[iliakur]

@AAraKKe so using the first line of the docstring as the short help text seems clearer to me. There's at least one place where we need the short_help argument, because we interpolate a value into it.

I see the point that people might start writing run-on short descriptions which won't fit, but I see the same danger with the short_help argument. It boils down to knowing a bit about click and also following some python docstring conventions.

I'd find it easier to pass on the knowledge that the docstring is one place for defining both short and long help messages.
Specifying the short_help which then overrides part of the docstring sounds less intuitive.

[AAraKKe]

I see the point that people might start writing run-on short descriptions which won't fit, but I see the same danger with the short_help argument.

Yes, that is true. I am just saying that having the short help also printed when we run --help on the command itself might be redundant since now the help will always contain a first short line that summarizes the command and a more detailed, longer explanation afterwards. If that is where we want to go I am ok with, not a strong opinion.

There's at least one place where we need the short_help argument, because we interpolate a value into it.

We can also interpolate variables in the docstring, what is that case where we need it?

EDIT: I just tested it and while we can interpolate in a docstring click does not seem to load the docstring as help anymore if interpolation is present. It seems that once we interpolate it the docstring does not behave as a "doc"string anymore and just as a multiline string.