[question] Is there a way to document the `Usage` section?

Is there a way to document the Usage section?

We use docopt to handle quite some devops task. There is quite some use-cases that are covered. We have split the script into multiple files but there are still around 20 different things you can do in the Usage section.

Documentation is very important in our organization. I wonder if there is a way that we can add documentation (some string) for different commands in the Usage section?

[SeeSpotRun]

It would be fairly easy (e.g. https://github.com/SeeSpotRun/docopt/commit/9e41facd761f618b22cf45f27819e5b30bb593c1) to modify docopt to allow brief descriptions at the end of each Usage pattern. This can improve readability, particularly if there are 20 different commands as per @brodul’s case:

Usage:
  prog add [--all]                   # Add something to somewhere
  prog remove <arg>                  # Remove something
  prog move <source> <destination>   # Move from <source> to <destination>

[keleshev]

Perhaps something like this?

Usage:
  prog add [--all]
  prog remove <arg>
  prog move <source> <destination>

Commands:
  add     Add something to somewhere
  remove  Remove something
  move    Move from <source> to <destination>