Fix various documentation bugs (#1678)

* Fix various documentation bugs

* Keep long option names, but don't include in Command Index

* Use long option name

* Explicitly designate sections to be listed in the Command Index

* Consistent menu bar titles

8 files changed, 97 insertions, 108 deletions

diff --git a/lib/spack/docs/basic_usage.rst b/lib/spack/docs/basic_usage.rst
index a5377415c7..bbedfff3fc 100644
--- a/lib/spack/docs/basic_usage.rst
+++ b/lib/spack/docs/basic_usage.rst
@@ -1,7 +1,7 @@
 .. _basic-usage:
 
 ===========
-Basic usage
+Basic Usage
 ===========
 
 The ``spack`` command has many *subcommands*.  You'll only need a
@@ -14,7 +14,7 @@ Spack to maintain this colorization.  E.g.:
 
     $ spack find | less -R
 
-It is recommend that the following be put in your ``.bashrc`` file:
+It is recommended that the following be put in your ``.bashrc`` file:
 
 .. code-block:: sh
 
@@ -28,7 +28,7 @@ To install software with Spack, you need to know what software is
 available.  You can see a list of available package names at the
 :ref:`package-list` webpage, or using the ``spack list`` command.
 
-.. _spack-list:
+.. _cmd-spack-list:
 
 ^^^^^^^^^^^^^^
 ``spack list``
@@ -57,13 +57,13 @@ All packages whose names start with a capital M:
 
 All packages whose names or descriptions contain Documentation:
 
-.. command-output:: spack list -d Documentation
+.. command-output:: spack list --search-description Documentation
 
 All packages whose names contain documentation case insensitive:
 
-.. command-output:: spack list -d documentation
+.. command-output:: spack list --search-description documentation
 
-.. _spack-info:
+.. _cmd-spack-info:
 
 ^^^^^^^^^^^^^^
 ``spack info``
@@ -82,7 +82,7 @@ viruses.
 :ref:`Dependencies <sec-specs>` and :ref:`virtual dependencies
 <sec-virtual-dependencies>` are described in more detail later.
 
-.. _spack-versions:
+.. _cmd-spack-versions:
 
 ^^^^^^^^^^^^^^^^^^
 ``spack versions``
@@ -107,7 +107,7 @@ able to find remote versions.
 Installing and uninstalling
 ---------------------------
 
-.. _spack-install:
+.. _cmd-spack-install:
 
 ^^^^^^^^^^^^^^^^^
 ``spack install``
@@ -180,14 +180,14 @@ configuration a **spec**.  In the commands above, ``mpileaks`` and
 ``mpileaks@3.0.4`` are both valid *specs*.  We'll talk more about how
 you can use them to customize an installation in :ref:`sec-specs`.
 
-.. _spack-uninstall:
+.. _cmd-spack-uninstall:
 
 ^^^^^^^^^^^^^^^^^^^
 ``spack uninstall``
 ^^^^^^^^^^^^^^^^^^^
 
 To uninstall a package, type ``spack uninstall <package>``.  This will ask
-the user for confirmation, and in case will completely remove the directory
+the user for confirmation before completely removing the directory
 in which the package was installed.
 
 .. code-block:: console
@@ -285,7 +285,7 @@ Seeing installed packages
 We know that ``spack list`` shows you the names of available packages,
 but how do you figure out which are already installed?
 
-.. _spack-find:
+.. _cmd-spack-find:
 
 ^^^^^^^^^^^^^^
 ``spack find``
@@ -798,7 +798,7 @@ it refers. Otherwise, it will prompt for a more qualified hash.
 Note that this will not work to reinstall a depencency uninstalled by
 ``spack uninstall --force``.
 
-.. _spack-providers:
+.. _cmd-spack-providers:
 
 ^^^^^^^^^^^^^^^^^^^
 ``spack providers``
@@ -1373,7 +1373,7 @@ an *extension*.  Suppose you have Python installed like so:
    -- linux-debian7-x86_64 / gcc@4.4.7 --------------------------------
    python@2.7.8
 
-.. _spack-extensions:
+.. _cmd-spack-extensions:
 
 ^^^^^^^^^^^^^^^^^^^^
 ``spack extensions``
@@ -1467,7 +1467,7 @@ for this case.  Instead of requiring users to load particular
 environment modules, you can *activate* the package within the Python
 installation:
 
-.. _spack-activate:
+.. _cmd-spack-activate:
 
 ^^^^^^^^^^^^^^^^^^
 ``spack activate``
@@ -1532,19 +1532,19 @@ into the same prefix.  Users who want a different version of a package
 can still get it by using environment modules, but they will have to
 explicitly load their preferred version.
 
-^^^^^^^^^^^^^^^^^^^^^
-``spack activate -f``
-^^^^^^^^^^^^^^^^^^^^^
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+``spack activate --force``
+^^^^^^^^^^^^^^^^^^^^^^^^^^
 
 If, for some reason, you want to activate a package *without* its
-dependencies, you can use ``spack activate -f``:
+dependencies, you can use ``spack activate --force``:
 
 .. code-block:: console
 
-   $ spack activate -f py-numpy
+   $ spack activate --force py-numpy
    ==> Activated extension py-numpy@1.9.1%gcc@4.4.7 arch=linux-debian7-x86_64-66733244 for python@2.7.8%gcc@4.4.7.
 
-.. _spack-deactivate:
+.. _cmd-spack-deactivate:
 
 ^^^^^^^^^^^^^^^^^^^^
 ``spack deactivate``
@@ -1622,7 +1622,7 @@ A nicer error message is TBD in future versions of Spack.
 Getting Help
 ------------
 
-.. _spack-help:
+.. _cmd-spack-help:
 
 ^^^^^^^^^^^^^^
 ``spack help``
diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py
index 57469964ee..08c57b8525 100644
--- a/lib/spack/docs/conf.py
+++ b/lib/spack/docs/conf.py
@@ -79,7 +79,7 @@ command_names = []
 for filename in glob('*rst'):
     with open(filename) as f:
         for line in f:
-            match = re.match(r'.. _(spack-[^:]*)', line)
+            match = re.match('.. _(cmd-spack-.*):', line)
             if match:
                 command_names.append(match.group(1).strip())
 
diff --git a/lib/spack/docs/developer_guide.rst b/lib/spack/docs/developer_guide.rst
index 27f03df57a..0942fdd9c3 100644
--- a/lib/spack/docs/developer_guide.rst
+++ b/lib/spack/docs/developer_guide.rst
@@ -331,7 +331,7 @@ Profiling
 
 Spack has some limited built-in support for profiling, and can report
 statistics using standard Python timing tools.  To use this feature,
-supply ``-p`` to Spack on the command line, before any subcommands.
+supply ``--profile`` to Spack on the command line, before any subcommands.
 
 .. _spack-p:
 
diff --git a/lib/spack/docs/features.rst b/lib/spack/docs/features.rst
index 57629997aa..2df1d182d6 100644
--- a/lib/spack/docs/features.rst
+++ b/lib/spack/docs/features.rst
@@ -1,5 +1,5 @@
 ================
-Feature overview
+Feature Overview
 ================
 
 This is a high-level overview of features that make Spack different
diff --git a/lib/spack/docs/getting_started.rst b/lib/spack/docs/getting_started.rst
index 3130d1e25c..7510693b18 100644
--- a/lib/spack/docs/getting_started.rst
+++ b/lib/spack/docs/getting_started.rst
@@ -135,7 +135,7 @@ compiler versions. Spack searches for compilers on your machine
 automatically the first time it is run. It does this by inspecting
 your ``PATH``.
 
-.. _spack-compilers:
+.. _cmd-spack-compilers:
 
 ^^^^^^^^^^^^^^^^^^^
 ``spack compilers``
@@ -559,7 +559,7 @@ flags to the ``icc`` command:
 
    .. code-block:: console
 
-       $ spack location -i gcc
+       $ spack location --install-dir gcc
        /home2/rpfische/spack2/opt/spack/linux-centos7-x86_64/gcc-4.9.3-iy4rw...
 
 #. Set up ``compilers.yaml``, for example:
@@ -761,14 +761,13 @@ by installing a new version of ``git`` and ``openssl``:
 #. Add the output of ``spack module loads git`` to your ``.bahsrc``.
 
 If this doesn't work, it is also possible to disable checking of SSL
-certificates by using either of:
+certificates by using:
 
 .. code-block:: console
 
-   $ spack -k install
    $ spack --insecure install
 
-Using ``-k/--insecure`` makes Spack disable SSL checking when fetching
+Using ``--insecure`` makes Spack disable SSL checking when fetching
 from websites and from git.
 
 .. warning::
@@ -810,7 +809,7 @@ or if environment modules don't work:
 
 .. code-block:: console
 
-    $ export PATH=`spack location -i curl`/bin:$PATH
+    $ export PATH=`spack location --install-dir curl`/bin:$PATH
 
 
 External commands are used by Spack in two places: within core Spack,
@@ -899,7 +898,7 @@ with Spack:
 
       TMP=`tempfile`
       echo >$TMP
-      MODULE_HOME=`spack location -i environment-modules`
+      MODULE_HOME=`spack location --install-dir environment-modules`
       MODULE_VERSION=`ls -1 $MODULE_HOME/Modules | head -1`
       ${MODULE_HOME}/Modules/${MODULE_VERSION}/bin/add.modules <$TMP
       cp .bashrc $TMP
diff --git a/lib/spack/docs/mirrors.rst b/lib/spack/docs/mirrors.rst
index c4d275a8fc..87ce3d96a2 100644
--- a/lib/spack/docs/mirrors.rst
+++ b/lib/spack/docs/mirrors.rst
@@ -52,7 +52,7 @@ contains tarballs for each package, named after each package.
    not standardize on a particular compression algorithm, because this
    would potentially require expanding and re-compressing each archive.
 
-.. _spack-mirror:
+.. _cmd-spack-mirror:
 
 ----------------
 ``spack mirror``
@@ -148,7 +148,7 @@ can supply a file with specs in it, one per line:
    boost@1.44:
    boost@1.39.0
    ...
-   $ spack mirror create -f specs.txt
+   $ spack mirror create --file specs.txt
    ...
 
 This is useful if there is a specific suite of software managed by
@@ -237,7 +237,7 @@ as other Spack mirrors (so it can be copied anywhere and referenced with a URL
 like other mirrors). The mirror is maintained locally (within the Spack
 installation directory) at :file:`var/spack/cache/`. It is always enabled (and
 is always searched first when attempting to retrieve files for an installation)
-but can be cleared with :ref:`purge <spack-purge>`; the cache directory can also
+but can be cleared with :ref:`purge <cmd-spack-purge>`; the cache directory can also
 be deleted manually without issue.
 
 Caching includes retrieved tarball archives and source control repositories, but
diff --git a/lib/spack/docs/packaging_guide.rst b/lib/spack/docs/packaging_guide.rst
index 6efb0078f6..15c3e0ca7f 100644
--- a/lib/spack/docs/packaging_guide.rst
+++ b/lib/spack/docs/packaging_guide.rst
@@ -33,7 +33,7 @@ easy.
 Creating & editing packages
 ---------------------------
 
-.. _spack-create:
+.. _cmd-spack-create:
 
 ^^^^^^^^^^^^^^^^
 ``spack create``
@@ -81,7 +81,7 @@ Spack will automatically download the number of tarballs you specify
 
 You do not *have* to download all of the versions up front. You can
 always choose to download just one tarball initially, and run
-:ref:`spack checksum <spack-checksum>` later if you need more.
+:ref:`cmd-spack-checksum` later if you need more.
 
 .. note::
 
@@ -93,14 +93,14 @@ always choose to download just one tarball initially, and run
       $ spack create --name cmake  http://www.cmake.org/files/v2.8/cmake-2.8.12.1.tar.gz
 
    If it fails entirely, you can get minimal boilerplate by using
-   :ref:`spack-edit-f`, or you can manually create a directory and
+   :ref:`spack edit --force <spack-edit-f>`, or you can manually create a directory and
    ``package.py`` file for the package in ``var/spack/repos/builtin/packages``.
 
 .. note::
 
    Spack can fetch packages from source code repositories, but,
    ``spack create`` will *not* currently create a boilerplate package
-   from a repository URL.  You will need to use :ref:`spack-edit-f`
+   from a repository URL.  You will need to use :ref:`spack edit --force <spack-edit-f>`
    and manually edit the ``version()`` directives to fetch from a
    repo.  See :ref:`vcs-fetch` for details.
 
@@ -198,7 +198,7 @@ The rest of the tasks you need to do are as follows:
 
 Before going into details, we'll cover a few more basics.
 
-.. _spack-edit:
+.. _cmd-spack-edit:
 
 ^^^^^^^^^^^^^^
 ``spack edit``
@@ -238,7 +238,7 @@ package:
 
 .. code-block:: console
 
-   $ spack edit -f foo
+   $ spack edit --force foo
 
 Unlike ``spack create``, which infers names and versions, and which
 actually downloads the tarball and checksums it for you, ``spack edit
@@ -271,8 +271,8 @@ Naming & directory structure
 ----------------------------
 
 This section describes how packages need to be named, and where they
-live in Spack's directory structure.  In general, :ref:`spack-create` and
-:ref:`spack-edit` handle creating package files for you, so you can skip
+live in Spack's directory structure.  In general, :ref:`cmd-spack-create` and
+:ref:`cmd-spack-edit` handle creating package files for you, so you can skip
 most of the details here.
 
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
@@ -371,7 +371,7 @@ some examples:
 =================  =================
 
 In general, you won't have to remember this naming convention because
-:ref:`spack-create` and :ref:`spack-edit` handle the details for you.
+:ref:`cmd-spack-create` and :ref:`cmd-spack-edit` handle the details for you.
 
 -----------------
 Trusted Downloads
@@ -590,7 +590,7 @@ Doing this for lots of files, or whenever a new package version is
 released, is tedious.  See ``spack checksum`` below for an automated
 version of this process.
 
-.. _spack-checksum:
+.. _cmd-spack-checksum:
 
 ^^^^^^^^^^^^^^^^^^
 ``spack checksum``
@@ -1120,7 +1120,7 @@ function gives you some benefits.  First, spack ensures that the
 ``patch()`` function is run once per code checkout.  That means that
 if you run install, hit ctrl-C, and run install again, the code in the
 patch function is only run once.  Also, you can tell Spack to run only
-the patching part of the build using the :ref:`spack-patch` command.
+the patching part of the build using the :ref:`cmd-spack-patch` command.
 
 ---------------
 Handling RPATHs
@@ -1134,7 +1134,7 @@ dynamic loader where to find its dependencies at runtime. You may be
 familiar with `LD_LIBRARY_PATH
 <http://tldp.org/HOWTO/Program-Library-HOWTO/shared-libraries.html>`_
 on Linux or `DYLD_LIBRARY_PATH
-<https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html>`
+<https://developer.apple.com/library/mac/documentation/Darwin/Reference/ManPages/man1/dyld.1.html>`_
 on Mac OS X.  RPATH is similar to these paths, in that it tells
 the loader where to find libraries.  Unlike them, it is embedded in
 the binary and not set in each user's environment.
@@ -1191,7 +1191,7 @@ information about the package, and to determine where to download its
 source code.
 
 Spack uses the tarball URL to extrapolate where to find other tarballs
-of the same package (e.g. in `spack checksum <spack-checksum_>`_, but
+of the same package (e.g. in :ref:`cmd-spack-checksum`, but
 this does not always work.  This section covers ways you can tell
 Spack to find tarballs elsewhere.
 
@@ -1202,7 +1202,7 @@ Spack to find tarballs elsewhere.
 ^^^^^^^^^^^^
 
 When spack tries to find available versions of packages (e.g. with
-`spack checksum <spack-checksum_>`_), it spiders the parent directory
+:ref:`cmd-spack-checksum`), it spiders the parent directory
 of the tarball in the ``url`` attribute.  For example, for libelf, the
 url is:
 
@@ -1859,7 +1859,7 @@ explicitly.  Concretization policies are discussed in more detail in
 :ref:`configuration`.  Sites using Spack can customize them to match
 the preferences of their own users.
 
-.. _spack-spec:
+.. _cmd-spack-spec:
 
 ^^^^^^^^^^^^^^
 ``spack spec``
@@ -2092,7 +2092,7 @@ discover its dependencies.
 
 If you want to see the environment that a package will build with, or
 if you want to run commands in that environment to test them out, you
-can use the :ref:`spack env <spack-env>` command, documented
+can use the :ref:`cmd-spack-env` command, documented
 below.
 
 .. _compiler-wrappers:
@@ -2871,7 +2871,7 @@ A typical package workflow might look like this:
 Below are some commands that will allow you some finer-grained
 control over the install process.
 
-.. _spack-fetch:
+.. _cmd-spack-fetch:
 
 ^^^^^^^^^^^^^^^
 ``spack fetch``
@@ -2886,7 +2886,7 @@ directory will be located under ``$SPACK_HOME/var/spack``.
 When run after the archive has already been downloaded, ``spack
 fetch`` is idempotent and will not download the archive again.
 
-.. _spack-stage:
+.. _cmd-spack-stage:
 
 ^^^^^^^^^^^^^^^
 ``spack stage``
@@ -2897,7 +2897,7 @@ the downloaded archive in its temporary directory, where it will be
 built by ``spack install``.  Similar to ``fetch``, if the archive has
 already been expanded,  ``stage`` is idempotent.
 
-.. _spack-patch:
+.. _cmd-spack-patch:
 
 ^^^^^^^^^^^^^^^
 ``spack patch``
@@ -2911,7 +2911,7 @@ this step if they have been.  If Spack discovers that patches didn't
 apply cleanly on some previous run, then it will restage the entire
 package before patching.
 
-.. _spack-restage:
+.. _cmd-spack-restage:
 
 ^^^^^^^^^^^^^^^^^
 ``spack restage``
@@ -2927,7 +2927,7 @@ Does this in one of two ways:
 #. If the source was checked out from a repository, this deletes the
    build directory and checks it out again.
 
-.. _spack-clean:
+.. _cmd-spack-clean:
 
 ^^^^^^^^^^^^^^^
 ``spack clean``
@@ -2938,7 +2938,7 @@ expanded/checked out source code *and* any downloaded archive.  If
 ``fetch``, ``stage``, or ``install`` are run again after this, Spack's
 build process will start from scratch.
 
-.. _spack-purge:
+.. _cmd-spack-purge:
 
 ^^^^^^^^^^^^^^^
 ``spack purge``
@@ -2996,7 +2996,7 @@ to get rid of the install prefix before you build again:
 Graphing dependencies
 ---------------------
 
-.. _spack-graph:
+.. _cmd-spack-graph:
 
 ^^^^^^^^^^^^^^^
 ``spack graph``
@@ -3056,7 +3056,7 @@ For ``csh`` and ``tcsh`` run:
 
 ``spack cd`` will then be available.
 
-.. _spack-cd:
+.. _cmd-spack-cd:
 
 ^^^^^^^^^^^^
 ``spack cd``
@@ -3081,14 +3081,14 @@ build it:
 directory containing the expanded ``libelf`` source code.  There are a
 number of other places you can cd to in the spack directory hierarchy:
 
-.. command-output:: spack cd -h
+.. command-output:: spack cd --help
 
 Some of these change directory into package-specific locations (stage
 directory, install directory, package directory) and others change to
-core spack locations.  For example, ``spack cd -m`` will take you to
+core spack locations.  For example, ``spack cd --module-dir`` will take you to
 the main python source directory of your spack install.
 
-.. _spack-env:
+.. _cmd-spack-env:
 
 ^^^^^^^^^^^^^
 ``spack env``
@@ -3117,7 +3117,7 @@ provide them after the spec argument to ``spack env``:
 This will cd to the build directory and then run ``configure`` in the
 package's build environment.
 
-.. _spack-location:
+.. _cmd-spack-location:
 
 ^^^^^^^^^^^^^^^^^^
 ``spack location``
@@ -3129,13 +3129,13 @@ cd'ing to it.  In bash, this:
 
 .. code-block:: console
 
-   $ cd $(spack location -b <spec>)
+   $ cd $(spack location --build-dir <spec>)
 
 is the same as:
 
 .. code-block:: console
 
-   $ spack cd -b <spec>
+   $ spack cd --build-dir <spec>
 
 ``spack location`` is intended for use in scripts or makefiles that
 need to know where packages are installed.  e.g., in a makefile you
@@ -3143,7 +3143,7 @@ might write:
 
 .. code-block:: makefile
 
-   DWARF_PREFIX = $(spack location -i libdwarf)
+   DWARF_PREFIX = $(spack location --install-dir libdwarf)
    CXXFLAGS += -I$DWARF_PREFIX/include
    CXXFLAGS += -L$DWARF_PREFIX/lib
 
diff --git a/lib/spack/docs/workflows.rst b/lib/spack/docs/workflows.rst
index b879fed124..314f57c8b5 100644
--- a/lib/spack/docs/workflows.rst
+++ b/lib/spack/docs/workflows.rst
@@ -79,7 +79,7 @@ The following set is not consistent:
    curl@7.50.1%gcc@5.3.0 arch=linux-SuSE11-x86_64
        ^openssl@system%gcc@5.3.0 arch=linux-SuSE11-x86_64
        ^zlib@1.2.8%gcc@5.3.0 arch=linux-SuSE11-x86_64
-   zlib@1.2.7%gcc@5.3.0 arch=linux-SuSE11-x86_64    
+   zlib@1.2.7%gcc@5.3.0 arch=linux-SuSE11-x86_64
 
 The compatibility of a set of installed packages determines what may
 be done with it.  It is always possible to ``spack load`` any set of
@@ -153,7 +153,7 @@ preferred versions and variants to use for packages.  For example:
 
 
 This approach will work as long as you are building packages for just
-one application.  
+one application.
 
 ^^^^^^^^^^^^^^^^^^^^^
 Multiple Applications
@@ -183,7 +183,6 @@ of usage:
 .. code-block:: sh
 
    #!/bin/sh
-   #
 
    compilers=(
        %gcc
@@ -218,10 +217,6 @@ of usage:
        done
    done
 
-
-
-
-
 ------------------------------
 Running Binaries from Packages
 ------------------------------
@@ -237,11 +232,11 @@ Find and Run
 The simplest way to run a Spack binary is to find it and run it!
 In many cases, nothing more is needed because Spack builds binaries
 with RPATHs.  Spack installation directories may be found with ``spack
-location -i`` commands.  For example:
+location --install-dir`` commands.  For example:
 
 .. code-block:: console
 
-   $ spack location -i cmake
+   $ spack location --install-dir cmake
    /home/me/spack2/opt/spack/linux-SuSE11-x86_64/gcc-5.3.0/cmake-3.6.0-7cxrynb6esss6jognj23ak55fgxkwtx7
 
 This gives the root of the Spack package; relevant binaries may be
@@ -249,7 +244,7 @@ found within it.  For example:
 
 .. code-block:: console
 
-   $ CMAKE=`spack location -i cmake`/bin/cmake
+   $ CMAKE=`spack location --install-dir cmake`/bin/cmake
 
 
 Standard UNIX tools can find binaries as well.  For example:
@@ -650,9 +645,9 @@ environments:
   Administrators might find things easier to maintain without the
   added "heavyweight" state of a view.
 
-==============================
+------------------------------
 Developing Software with Spack
-==============================
+------------------------------
 
 For any project, one needs to assemble an
 environment of that application's dependencies.  You might consider
@@ -700,10 +695,9 @@ can be seamlessly integrated into the Spack ecosystem.  We will show
 how this process works by example, assuming the software you are
 creating is called ``mylib``.
 
-
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 Write the CMake Build
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 For now, the techniques in this section only work for CMake-based
 projects, although they could be easily extended to other build
@@ -731,7 +725,7 @@ The ``CMakeLists.txt`` file should be written as normal.  A few caveats:
 
    # when building, don't use the install RPATH already
    # (but later on when installing)
-   SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE) 
+   SET(CMAKE_BUILD_WITH_INSTALL_RPATH FALSE)
 
    # add the automatically determined parts of the RPATH
    # which point to directories outside the build tree to the install RPATH
@@ -770,9 +764,9 @@ The ``CMakeLists.txt`` file should be written as normal.  A few caveats:
 
 .. _write-the-spack-package:
 
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 Write the Spack Package
------------------------
+^^^^^^^^^^^^^^^^^^^^^^^
 
 The Spack package also needs to be written, in tandem with setting up
 the build (for example, CMake).  The most important part of this task
@@ -838,9 +832,9 @@ used for development:
    not used in development.  Don't worry if you don't have any, or if
    they are behind a firewall.
 
-----------------
+^^^^^^^^^^^^^^^^
 Build with Spack
-----------------
+^^^^^^^^^^^^^^^^
 
 Now that you have a Spack package, you can use Spack to find its
 dependencies automatically.  For example:
@@ -894,11 +888,9 @@ into Git or downloading tarballs.
    problems in our experience, as long as your project sets
    RPATHs as shown above.  You DO use RPATHs, right?
 
-    
-
---------------------
+^^^^^^^^^^^^^^^^^^^^
 Build Other Software
---------------------
+^^^^^^^^^^^^^^^^^^^^
 
 Now that you've built ``mylib`` with Spack, you might want to build
 another package that depends on it --- for example, ``myapp``.  This
@@ -924,9 +916,9 @@ for example:
 
 .. _release-your-software:
 
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 Release Your Software
----------------------
+^^^^^^^^^^^^^^^^^^^^^
 
 You are now ready to release your software as a tarball with a
 numbered version, and a Spack package that can build it.  If you're
@@ -952,7 +944,7 @@ hosted on GitHub, this process will be a bit easier.
       ==> Found 1 versions of mylib
         0.1.2     https://github.com/citibeth/mylib/tarball/v0.1.2
 
-      How many would you like to checksum? (default is 5, q to abort) 
+      How many would you like to checksum? (default is 5, q to abort)
       ==> Downloading...
       ==> Trying to fetch from https://github.com/citibeth/mylib/tarball/v0.1.2
       ######################################################################## 100.0%
@@ -969,11 +961,9 @@ hosted on GitHub, this process will be a bit easier.
    Spack concretization will always prefer numbered version to
    non-numeric versions.  Users will only get it if they ask for it.
 
-
-
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 Distribute Your Software
-------------------------
+^^^^^^^^^^^^^^^^^^^^^^^^
 
 Once you've released your software, other people will want to build
 it; and you will need to tell them how.  In the past, that has meant a
@@ -1012,9 +1002,9 @@ Spack is the best way to install it:
    systems.  The :ref:`getting_started` section should cover this, but
    there could always be issues.
 
--------------------
+^^^^^^^^^^^^^^^^^^^
 Other Build Systems
--------------------
+^^^^^^^^^^^^^^^^^^^
 
 ``spack setup`` currently only supports CMake-based builds, in
 packages that subclass ``CMakePackage``.  The intent is that this
@@ -1028,9 +1018,9 @@ Python Distutils is another popular build system that should get
 directly in the user's ``PYTHONPATH``.  Then, edits in source files
 are immediately available to run without any install process at all!
 
-----------
+^^^^^^^^^^
 Conclusion
-----------
+^^^^^^^^^^
 
 The ``spack setup`` development workflow provides better automation,
 flexibility and safety than workflows relying on environment modules
@@ -1049,9 +1039,9 @@ or filesystem views.  However, it has some drawbacks:
    integrate Spack explicitly in their workflow.  Not all users are
    willing to do this.
 
-==================
+------------------
 Upstream Bug Fixes
-==================
+------------------
 
 It is not uncommon to discover a bug in an upstream project while
 trying to build with Spack.  Typically, the bug is in a package that
@@ -1059,9 +1049,9 @@ serves a dependency to something else.  This section describes
 procedure to work around and ultimately resolve these bugs, while not
 delaying the Spack user's main goal.
 
------------------
+^^^^^^^^^^^^^^^^^
 Buggy New Version
------------------
+^^^^^^^^^^^^^^^^^
 
 Sometimes, the old version of a package works fine, but a new version
 is buggy.  For example, it was once found that `Adios did not build
@@ -1092,9 +1082,9 @@ procedure is:
       depends_on('hdf5@:1.9', when='@:1.10.0')
       depends_on('hdf5', when='@1.10.1:')
 
-----------------
+^^^^^^^^^^^^^^^^
 No Version Works
-----------------
+^^^^^^^^^^^^^^^^
 
 Sometimes, *no* existing versions of a dependency work for a build.
 This typically happens when developing a new project: only then does
@@ -1183,9 +1173,9 @@ of ``py-proj/package.py`` is instructive here:
    bugfix, then the unofficial ``version()`` line should be removed
    from the Spack package.
 
--------
+^^^^^^^
 Patches
--------
+^^^^^^^
 
 Spack's source patching mechanism provides another way to fix bugs in
 upstream projects.  This has advantages and disadvantages compared to the procedures above.