Improve the Spack command reference

[tgamblin]

This improves the command reference in the docs. Previously, the command reference listed only commands for which we explicitly wrote documentation. Now it lists all Spack commands and shows their usage. This was sort of inspired by the Docker CLI reference.

This also contains a number of improvements to spack <cmd> -h output.

• Add a spack commands command to list commands in various formats (including RST)
• Rework the docs to use spack commands to generate the command reference. Docs now have an index by type of command and show full usage.
• Add proper help for spack buildcache subcommands
• Fix some bugs with spack -h argument display
• Display options in help output as [-abc], not [-a] [-b] [-c]
• Clean up the metavar for --scope arguments in configuration commands like mirror, repo, etc. (it's now much shorter)

You can look at a preview here.

@JusticeForMikeBrown: you might like this, as it would've saved you a few issue submissions.

[adamjstewart]

This is cool. Is it possible to add short and long descriptions to argparse commands? What I'm envisioning is that when you run spack help, you get the name and short description of every command, but when you run spack help list, you get the short and long description of the command. The long description would be similar to a man page, with detailed examples of common usage. Of course, someone would need to write these long descriptions, but it would get us one step closer to a future where if you ever have a question about how to use a command, spack help <command> gives you everything you need to know.

[tgamblin]

@adamjstewart: it's possible in the sense that we could add a long help attribute to commands, but we'd need to rework the help formatter to do it. We already have a custom help formatter in spack.main.SpackHelpFormatter, so it wouldn't be too hard.

Then again, I think other tools tend to deal with this differently. git and brew use manpages for this, and it may be that we should just write longer rst sections for each command, turn them into manpages, and have spack help <cmd> give you the manpage like git help <cmd> does, and keep the short descriptions in spack <cmd> -h. I actually like the rst way better because there's room for more detail and there are well defined rules for formatting the long help. Wedging all this into argparse alone seems like a lot of work for only a little gain when there are more versatile ways to do the same thing.

Thoughts?