Add tab completion & update docs for buildcache

This adds tab completion and fixes some formatting issues in the
documentation for the "spack buildcache" command.

lib/spack/docs/binary_caches.rst

@@ -1,108 +1,132 @@
 .. _binary_caches:
 
+============
 Build caches
 ============
 
 Some sites may encourage users to set up their own test environments
-before carrying out central installations, or some users prefer to set
+before carrying out central installations, or some users may prefer to set
 up these environments on their own motivation. To reduce the load of
 recompiling otherwise identical package specs in different installations,
-installed packages can be put into build cache tarballs, uploaded to 
+installed packages can be put into build cache tarballs, uploaded to
-your spack mirror and then downloaded and installed by others.
+your Spack mirror and then downloaded and installed by others.
 
 
+--------------------------
 Creating build cache files
 --------------------------
 
 A compressed tarball of an installed package is created. Tarballs are created
 for all of its link and run dependency packages as well. Compressed tarballs are
-signed with gpg and signature and tarball and put in a ".spack" file. Optionally
+signed with gpg and signature and tarball and put in a ``.spack`` file. Optionally,
-, the rpaths ( and ids and deps on macOS ) can be changed to paths relative to 
+the rpaths (and ids and deps on macOS) can be changed to paths relative to
-the spack install tree before the tarball is created.
+the Spack install tree before the tarball is created.
 
 Build caches are created via:
 
-.. code-block:: sh
+.. code-block:: console
 
-   $ spack buildcache create 
+   $ spack buildcache create
 
 
+---------------------------------------
 Finding or installing build cache files
 ---------------------------------------
 
-To find build caches or install build caches, a spack mirror must be configured
+To find build caches or install build caches, a Spack mirror must be configured
-with
+with:
- 
-``spack mirror add <name> <url>``. 
 
-Build caches are found via: 
+.. code-block:: console
 
-.. code-block:: sh
+   $ spack mirror add <name> <url>
+
+Build caches are found via:
+
+.. code-block:: console
 
    $ spack buildcache list
 
 Build caches are installed via:
 
-.. code-block:: sh
+.. code-block:: console
 
-   $ spack buildcache install 
+   $ spack buildcache install
-   
 
+
+----------
 Relocation
 ----------
 
-Initial build and later installation do not necessarily happen at the same 
+Initial build and later installation do not necessarily happen at the same
-location. Spack provides a relocation capability and corrects for RPATHs and 
+location. Spack provides a relocation capability and corrects for RPATHs and
-non-relocatable scripts. However, many packages compile paths into binary 
+non-relocatable scripts. However, many packages compile paths into binary
-artificats directly. In such cases, the build instructions of this package would
+artifacts directly. In such cases, the build instructions of this package would
 need to be adjusted for better re-locatability.
 
+.. _cmd-spack-buildcache:
 
-Usage 
+--------------------
------
+``spack buildcache``
-spack buildcache create <>
+--------------------
-^^^^^^^^^^^^^^^^^^^^^^^^^^
-Create tarball of installed spack package and all dependencies. 
-Tarballs is checksummed and signed if gpg2 is available.
-Places them in a directory build_cache that can be copied to a mirror.
-Commands like "spack buildcache install" will search it for pre-compiled packages.
- 
 
-options:
-
--d <path> : directory in which "build_cache" direcory is created, defaults to "."
--f : overwrite ".spack" file in "build_cache" directory if it exists
--k <key> : the key to sign package with. In the case where multiple keys exist, the package will be unsigned unless -k is used.
--r : make paths in binaries relative before creating tarball
--y : answer yes to all create unsigned "build_cache" questions
-<> : list of package specs or package hashes with leading /
-
-spack buildcache list <>
-^^^^^^^^^^^^^^^^^^^^^^^^
-Retrieves all specs for build caches available on a spack mirror.
-
-options:
-
-<> string to be matched to matched to begining of listed concretized short 
-specs, eg. "spack buildcache list gcc" with print only commands to install gcc
-package(s)
-
-spack buildcache install <>
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^
-Retrieves all specs for build caches available on a spack mirror and installs build caches 
+``spack buildcache create``
-with specs matching the specs or hashes input. 
+^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-options:
+Create tarball of installed Spack package and all dependencies.
+Tarballs are checksummed and signed if gpg2 is available.
+Places them in a directory ``build_cache`` that can be copied to a mirror.
+Commands like ``spack buildcache install`` will search it for pre-compiled packages.
 
--f : remove install directory if it exists before unpacking tarball
+==============  ========================================================================================================================
--y : answer yes to all to don't verify package with gpg questions
+Arguments       Description
-<> : list of package specs or package hashes with leading /
+==============  ========================================================================================================================
+``<packages>``  list of package specs or package hashes with leading ``/``
+``-d <path>``   directory in which ``build_cache`` directory is created, defaults to ``.``
+``-f``          overwrite ``.spack`` file in ``build_cache`` directory if it exists
+``-k <key>``    the key to sign package with. In the case where multiple keys exist, the package will be unsigned unless ``-k`` is used.
+``-r``          make paths in binaries relative before creating tarball
+``-y``          answer yes to all create unsigned ``build_cache`` questions
+==============  ========================================================================================================================
 
-spack buildcache keys
+^^^^^^^^^^^^^^^^^^^^^^^^^
-^^^^^^^^^^^^^^^^^^^^^
+``spack buildcache list``
-List public keys available on spack mirror.
+^^^^^^^^^^^^^^^^^^^^^^^^^
 
-options:
+Retrieves all specs for build caches available on a Spack mirror.
 
--i : trust the keys downloaded with prompt for each
+==============  ==============================================================================
--y : answer yes to all trust all keys downloaded
+Arguments       Description
+==============  ==============================================================================
+``<packages>``  string to be matched to matched to beginning of listed concretized short specs
+==============  ==============================================================================
+
+E.g. ``spack buildcache list gcc`` with print only commands to install ``gcc`` package(s)
+
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+``spack buildcache install``
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Retrieves all specs for build caches available on a Spack mirror and installs build caches
+with specs matching the specs or hashes input.
+
+==============  ==============================================================
+Arguments       Description
+==============  ==============================================================
+``<packages>``  list of package specs or package hashes with leading ``/``
+``-f``          remove install directory if it exists before unpacking tarball
+``-y``          answer yes to all to don't verify package with gpg questions
+==============  ==============================================================
+
+^^^^^^^^^^^^^^^^^^^^^^^^^
+``spack buildcache keys``
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+List public keys available on Spack mirror.
+
+=========  ==============================================
+Arguments  Description
+=========  ==============================================
+``-i``     trust the keys downloaded with prompt for each
+``-y``     answer yes to all trust all keys downloaded
+=========  ==============================================

lib/spack/docs/index.rst

@@ -63,9 +63,9 @@ or refer to the full manual below.
    mirrors
    module_file_support
    repositories
+   binary_caches
    command_index
    package_list
-   binary_caches
 
 .. toctree::
    :maxdepth: 2

share/spack/spack-completion.bash

@@ -152,6 +152,50 @@ function _spack_build {
     fi
 }
 
+function _spack_buildcache {
+    if $list_options
+    then
+        compgen -W "-h --help" -- "$cur"
+    else
+        compgen -W "create install keys list" -- "$cur"
+    fi
+}
+
+function _spack_buildcache_create {
+    if $list_options
+    then
+        compgen -W "-h --help -r --rel -f --force -y --yes-to-all -k --key
+                    -d --directory" -- "$cur"
+    else
+        compgen -W "$(_all_packages)" -- "$cur"
+    fi
+}
+
+function _spack_buildcache_install {
+    if $list_options
+    then
+        compgen -W "-h --help -f --force -y --yes-to-all" -- "$cur"
+    else
+        compgen -W "$(_all_packages)" -- "$cur"
+    fi
+}
+
+function _spack_buildcache_keys {
+    if $list_options
+    then
+        compgen -W "-h --help -i --install -y --yes-to-all" -- "$cur"
+    fi
+}
+
+function _spack_buildcache_list {
+    if $list_options
+    then
+        compgen -W "-h --help" -- "$cur"
+    else
+        compgen -W "$(_all_packages)" -- "$cur"
+    fi
+}
+
 function _spack_cd {
     if $list_options
     then