Add usage examples to --help output

[Dzhud]

Add usage examples to the --help output for pip-compile and pip-sync commands, making it easier for users to quickly see common usage patterns without consulting the full documentation.

Closes #1142

$ pip-compile --help

Examples:

  Compile requirements.in to requirements.txt:
  $ pip-compile

  Upgrade all packages to their latest versions:
  $ pip-compile --upgrade

  Upgrade specific packages:
  $ pip-compile -P django -P requests

  Include package hashes for extra security:
  $ pip-compile --generate-hashes

  Compile with optional extras:
  $ pip-compile --extra dev pyproject.toml

Contributor checklist

• Included tests for the changes.
• A change note is created in changelog.d/ (see changelog.d/README.md
  for instructions) or the PR text says "no changelog needed".

Maintainer checklist

• If no changelog is needed, apply the bot:chronographer:skip label.
• Assign the PR to an existing or new milestone for the target version
  (following Semantic Versioning).

[sirosen]

Hi, thanks for working on this! I'm going to make a small edit to your PR text to restore the maintainer checklist; we use that to make sure PRs get assigned to a planned release.

pre-commit.ci indicates a pymarkdown failure. You should be able to fix that by wrapping the text in your changelog note at 80 chars.

I think the epilog is the right place for these, but I have two concerns about the current proposed text.

1. Placing descriptions after commands, rather than before, may be confusing.
2. These lists are fairly long, relative to help output. Can we make them shorter? Are there any of these examples we might skip?

For (1), I think it's a potential issue that users will see text like this:

    pip-sync --dry-run

Preview what would be installed or uninstalled.

    pip-sync --ask

It would be easy to (incorrectly) believe that description goes with the --ask flag. I think a better approach would be to go before, and end with a colon, as in:

Preview what would be installed or uninstalled:

    pip-sync --dry-run

It may also be nice to indent the descriptions, so that they aren't at the same indent level as the Examples: header.

We could also add a $ sigil to show where the command starts. The result might be more like...

Examples:

    Preview what would be installed or uninstalled:
    $ pip-sync --dry-run

Regarding (2), you've already applied some judgement about which things to use as examples, and I like this starting set. I don't see any which "definitely" should be removed, but there is some overlap between examples. I think that if we can remove a couple of these, it may make the help text even better!

[Dzhud]

Thanks for the detailed feedback! I've updated the PR to address your points. Let me know if anything else needs adjusting.

[sirosen]

I like the edited-down lists of examples you used. I think the content there is great -- no notes!

I just got a chance to pull down the PR and try it out. There's a minor issue that I'm trying to decide whether or not we need to address, which is that the helptext formatter in click prints the epilog indented two spaces:

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

  
  Examples:
  
      Compile requirements.in to requirements.txt:
      $ pip-compile

This isn't trivially fixable -- the simplest workaround requires override a click class which I think may be an internal API.¹ I'm going to take a little bit to think about this, and maybe make some time this weekend to see how I feel about this if I cook up a fix.

Footnotes

1. There's a long-standing issue with click's APIs exposing more implementation details than the maintainers want. I don't think they need a ticket from us about this -- it's just a known problem for that library, which they're working on. ↩