Rework command reference in docs, add spack commands command

- command reference now includes usage for all Spack commands as output
  by `spack help`.  Each command usage links to any related section in
  the docs.

- added `spack commands` command which can list command names,
  subcommands, and generate RST docs for commands.

- added `llnl.util.argparsewriter`, which analyzes an argparse parser and
  calls hooks for description, usage, options, and subcommands

lib/spack/docs/conf.py

@@ -76,19 +76,23 @@
 #
 # Find all the `cmd-spack-*` references and add them to a command index
 #
-command_names = []
+import spack
+command_names = spack.cmd.all_commands
+documented_commands = set()
 for filename in glob('*rst'):
     with open(filename) as f:
         for line in f:
-            match = re.match('.. _(cmd-spack-.*):', line)
+            match = re.match('.. _cmd-(spack-.*):', line)
             if match:
-                command_names.append(match.group(1).strip())
+                documented_commands.add(match.group(1).strip())
 
+os.environ['COLUMNS'] = '120'
 shutil.copy('command_index.in', 'command_index.rst')
 with open('command_index.rst', 'a') as index:
-    index.write('\n')
-    for cmd in sorted(command_names):
-        index.write('   * :ref:`%s`\n' % cmd)
+    subprocess.Popen(
+        [spack_root + '/bin/spack', 'commands', '--format=rst'] + list(
+            documented_commands),
+        stdout=index)
 
 #
 # Run sphinx-apidoc
@@ -115,7 +119,7 @@
 # This also avoids issues where some of these symbols shadow core spack
 # modules.  Sphinx will complain about duplicate docs when this happens.
 #
-import fileinput, spack
+import fileinput
 handling_spack = False
 for line in fileinput.input('spack.rst', inplace=1):
     if handling_spack: