--help needs some love

[Gustavo Niemeyer]

Typing "snapcraft <any subcommand> --help" shows the same output of "snapcraft --help".

For clarity, each subcommand should hold its own documentation, and options for subcommands should be removed from the global documentation.

There's also no need to have a huge usage list at the top. Usage for each subcommand should ideally be inside that specific subcommand's help.

Also, the summary of the "build" stage holds documentation for its option:

"""
  clean Remove content - cleans downloads, builds or install artifacts.
  pull Download or retrieve artifacts defined for a part.
  build Build artifacts defined for a part. Build systems capable of
               running parallel build jobs will do so unless
               "--no-parallel-build" is specified.
"""

The option should be documented under the options header as usual, instead of the summary.

Also, these summaries might be moved to the third person perhaps. E.g.:

  pull Downloads or retrieves artifacts defined for a part.

and the "clean" one might also be shortened to something like:

  clean Removes downloads, builds, or install artifacts.

Anyway, sorry for the sausage report. This is all related, but not quite.

[Sergio Schvezov (sergiusens)]

This change means we would need to move away from docopts

[Leo Arias (elopio)]

Raising the priority, because the help is pretty bad now with the big list of snapcraft commands that we have.

[Sergio Schvezov (sergiusens)]

https://github.com/snapcore/snapcraft/pull/1307