Merge branch 'features/travis' into develop

.flake8

@@ -5,8 +5,10 @@
 # rationale is.
 #
 # Let people line things up nicely:
+# - E129: visually indented line with same indent as next logical line
 # - E221: multiple spaces before operator
-# - E241: multiple spaces after ‘,’
+# - E241: multiple spaces after ','
+# - E272: multiple spaces before keyword
 #
 # Let people use terse Python features:
 # - E731 : lambda expressions
@@ -15,9 +17,10 @@
 # - F403: disable wildcard import
 #
 # These are required to get the package.py files to test clean.
-# - F821: undefined name (needed for cmake, configure, etc.)
+# - F405: `name` may be undefined, or undefined from star imports: `module`
-# - F999: name name be undefined or undefined from star imports.
+# - F821: undefined name `name` (needed for cmake, configure, etc.)
+# - F999: syntax error in doctest
 #
 [flake8]
-ignore = E129,E221,E241,E272,E731,F403,F821,F999,F405
+ignore = E129,E221,E241,E272,E731,F403,F405,F821,F999
 max-line-length = 79

.travis.yml

@@ -1,27 +1,38 @@
 language: python
 
+# Construct build matrix
 python:
-  - "2.6"
+  - 2.6
-  - "2.7"
+  - 2.7
-env:
+
-  - TEST_TYPE=unit
+env:
-  - TEST_TYPE=flake8
+  - TEST_SUITE=unit
+  - TEST_SUITE=flake8
+  - TEST_SUITE=doc
 
-# Exclude flake8 from python 2.6
 matrix:
   exclude:
-  - python: "2.6"
+  - python: 2.6
-    env: TEST_TYPE=flake8
+    # Flake8 no longer supports Python 2.6
+    env: TEST_SUITE=flake8
 
 # Use new Travis infrastructure (Docker can't sudo yet)
 sudo: false
 
-# Install coveralls to obtain code coverage
+# Docs need graphviz to build
-install:
+addons:
-  - "pip install coveralls"
+  apt:
-  - "pip install flake8"
+    packages:
+      - graphviz
 
-before_install:
+# Install various dependencies
+install:
+  - pip install coveralls
+  - pip install flake8
+  - pip install sphinx
+  - pip install mercurial
+
+before_script:
   # Need this for the git tests to succeed.
   - git config --global user.email "spack@example.com"
   - git config --global user.name "Test User"
@@ -29,18 +40,13 @@ before_install:
   # Need this to be able to compute the list of changed files
   - git fetch origin develop:develop
 
-script:
+script: share/spack/qa/run-$TEST_SUITE-tests
-  # Run unit tests with code coverage plus install libdwarf
-  - 'if [ "$TEST_TYPE" = "unit" ]; then share/spack/qa/run-unit-tests; fi'
-  # Run flake8 code style checks.
-  - 'if [ "$TEST_TYPE" = "flake8" ]; then share/spack/qa/run-flake8; fi'
 
 after_success:
-  - 'if [ "$TEST_TYPE" = "unit" ] && [ "$TRAVIS_PYTHON_VERSION" = "2.7" ]; then coveralls; fi'
+  - if [[ $TEST_SUITE == unit && $TRAVIS_PYTHON_VERSION == 2.7 ]]; then coveralls; fi
 
 notifications:
   email:
-    recipients:
+    recipients: tgamblin@llnl.gov
-      - tgamblin@llnl.gov
     on_success: change
     on_failure: always

README.md

@@ -68,7 +68,7 @@ Before you send a PR, your code should pass the following checks:
 * Your contribution will need to pass the `spack test` command.
   Run this before submitting your PR.
 
-* Also run the `share/spack/qa/run-flake8` script to check for PEP8 compliance.
+* Also run the `share/spack/qa/run-flake8-tests` script to check for PEP8 compliance.
   To encourage contributions and readability by a broad audience,
   Spack uses the [PEP8](https://www.python.org/dev/peps/pep-0008/) coding
   standard with [a few exceptions](https://github.com/LLNL/spack/blob/develop/.flake8).

bin/spack

@@ -56,8 +56,15 @@ with warnings.catch_warnings():
 # Spack, were removed, but shadow system modules that Spack still
 # imports.  If we leave them, Spack will fail in mysterious ways.
 # TODO: more elegant solution for orphaned pyc files.
-orphaned_pyc_files = [os.path.join(SPACK_EXTERNAL_LIBS, n)
+orphaned_pyc_files = [
-                      for n in ('functools.pyc', 'ordereddict.pyc')]
+    os.path.join(SPACK_EXTERNAL_LIBS, 'functools.pyc'),
+    os.path.join(SPACK_EXTERNAL_LIBS, 'ordereddict.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'platforms', 'cray_xc.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'cmd', 'package-list.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'cmd', 'test-install.pyc'),
+    os.path.join(SPACK_LIB_PATH, 'spack', 'cmd', 'url-parse.pyc')
+]
+
 for pyc_file in orphaned_pyc_files:
     if not os.path.exists(pyc_file):
         continue
@@ -120,7 +127,8 @@ subparsers = parser.add_subparsers(metavar='SUBCOMMAND', dest="command")
 import spack.cmd
 for cmd in spack.cmd.commands:
     module = spack.cmd.get_module(cmd)
-    subparser = subparsers.add_parser(cmd, help=module.description)
+    cmd_name = cmd.replace('_', '-')
+    subparser = subparsers.add_parser(cmd_name, help=module.description)
     module.setup_parser(subparser)
 
 # Just print help and exit if run with no arguments at all
@@ -156,7 +164,7 @@ def main():
         spack.curl.add_default_arg('-k')
 
     # Try to load the particular command asked for and run it
-    command = spack.cmd.get_command(args.command)
+    command = spack.cmd.get_command(args.command.replace('-', '_'))
     try:
         return_val = command(parser, args)
     except SpackError as e:

lib/spack/docs/case_studies.rst

@@ -1,5 +1,6 @@
+=======================================
 Using Spack for CMake-based Development
-==========================================
+=======================================
 
 These are instructions on how to use Spack to aid in the development
 of a CMake-based project.  Spack is used to help find the dependencies
@@ -7,25 +8,27 @@ for the project, configure it at development time, and then package it
 it in a way that others can install.  Using Spack for CMake-based
 development consists of three parts:
 
-1. Setting up the CMake build in your software
+#. Setting up the CMake build in your software
-2. Writing the Spack Package
+#. Writing the Spack Package
-3. Using it from Spack.
+#. Using it from Spack.
-
 
+--------------------------
 Setting Up the CMake Build
----------------------------------------
+--------------------------
 
 You should follow standard CMake conventions in setting up your
 software, your CMake build should NOT depend on or require Spack to
 build.  See here for an example:
+
 https://github.com/citibeth/icebin
 
 Note that there's one exception here to the rule I mentioned above.
-In ``CMakeLists.txt``, I have the following line::
+In ``CMakeLists.txt``, I have the following line:
+
+.. code-block:: none
 
    include_directories($ENV{CMAKE_TRANSITIVE_INCLUDE_PATH})
 
-
 This is a hook into Spack, and it ensures that all transitive
 dependencies are included in the include path.  It's not needed if
 everything is in one tree, but it is (sometimes) in the Spack world;
@@ -48,12 +51,14 @@ correctly.  Not only is this a good idea and nice, but it also ensures
 that your package will build the same with or without ``spack
 install``.
 
+-------------------------
 Writing the Spack Package
----------------------------------------
+-------------------------
 
 Now that you have a CMake build, you want to tell Spack how to
 configure it.  This is done by writing a Spack package for your
 software.  See here for example:
+
 https://github.com/citibeth/spack/blob/efischer/develop/var/spack/repos/builtin/packages/icebin/package.py
 
 You need to subclass ``CMakePackage``, as is done in this example.
@@ -61,27 +66,29 @@ This enables advanced features of Spack for helping you in configuring
 your software (keep reading...).  Instead of an ``install()`` method
 used when subclassing ``Package``, you write ``configure_args()``.
 See here for more info on how this works:
+
 https://github.com/LLNL/spack/pull/543/files
 
 NOTE: if your software is not publicly available, you do not need to
 set the URL or version.  Or you can set up bogus URLs and
 versions... whatever causes Spack to not crash.
 
-
+-------------------
 Using it from Spack
---------------------------------
+-------------------
 
 Now that you have a Spack package, you can get Spack to setup your
 CMake project for you.  Use the following to setup, configure and
-build your project::
+build your project:
 
-    cd myproject
+.. code-block:: console
-    spack spconfig myproject@local
-    mkdir build; cd build
-    ../spconfig.py ..
-    make
-    make install
 
+   $ cd myproject
+   $ spack spconfig myproject@local
+   $ mkdir build; cd build
+   $ ../spconfig.py ..
+   $ make
+   $ make install
 
 Everything here should look pretty familiar here from a CMake
 perspective, except that ``spack spconfig`` creates the file
@@ -94,11 +101,11 @@ If your project is publicly available (eg on GitHub), then you can
 ALSO use this setup to "just install" a release version without going
 through the manual configuration/build step.  Just do:
 
-1. Put tag(s) on the version(s) in your GitHub repo you want to be release versions.
+#. Put tag(s) on the version(s) in your GitHub repo you want to be release versions.
 
-2. Set the ``url`` in your ``package.py`` to download a tarball for
+#. Set the ``url`` in your ``package.py`` to download a tarball for
    the appropriate version.  (GitHub will give you a tarball for any
-   version in the repo, if you tickle it the right way).  For example::
+   version in the repo, if you tickle it the right way).  For example:
 
    https://github.com/citibeth/icebin/tarball/v0.1.0
 
@@ -106,35 +113,40 @@ through the manual configuration/build step.  Just do:
    download the tarball and run ``md5sum`` to determine the
    appropriate checksum for it).
 
-3. Now you should be able to say ``spack install myproject@version``
+#. Now you should be able to say ``spack install myproject@version``
    and things "just work."
 
 NOTE... in order to use the features outlined in this post, you
 currently need to use the following branch of Spack:
+
 https://github.com/citibeth/spack/tree/efischer/develop
 
 There is a pull request open on this branch (
 https://github.com/LLNL/spack/pull/543 ) and we are working to get it
 integrated into the main ``develop`` branch.
 
-
+------------------------
 Activating your Software
--------------------------------------
+------------------------
 
 Once you've built your software, you will want to load it up.  You can
 use ``spack load mypackage@local`` for that in your ``.bashrc``, but
 that is slow.  Try stuff like the following instead:
 
 The following command will load the Spack-installed packages needed
-for basic Python use of IceBin::
+for basic Python use of IceBin:
 
-    module load `spack module find tcl icebin netcdf cmake@3.5.1`
+.. code-block:: console
-    module load `spack module find --dependencies tcl py-basemap py-giss`
+
+   $ module load `spack module find tcl icebin netcdf cmake@3.5.1`
+   $ module load `spack module find --dependencies tcl py-basemap py-giss`
 
 
 You can speed up shell startup by turning these into ``module load`` commands.
 
-1. Cut-n-paste the script ``make_spackenv``::
+#. Cut-n-paste the script ``make_spackenv``:
+
+   .. code-block:: sh
 
       #!/bin/sh
       #
@@ -145,17 +157,19 @@ You can speed up shell startup by turning these into ``module load`` commands.
       spack module find --shell tcl git icebin@local ibmisc netcdf cmake@3.5.1 > $SPACKENV
       spack module find --dependencies --shell tcl py-basemap py-giss >> $SPACKENV
 
-2. Add the following to your ``.bashrc`` file::
+#. Add the following to your ``.bashrc`` file:
+
+   .. code-block:: sh
 
       source $HOME/spackenv.sh
       # Preferentially use your checked-out Python source
       export PYTHONPATH=$HOME/icebin/pylib:$PYTHONPATH
 
-3. Run ``sh make_spackenv`` whenever your Spack installation changes (including right now).
+#. Run ``sh make_spackenv`` whenever your Spack installation changes (including right now).
-
 
+-----------
 Giving Back
--------------------
+-----------
 
 If your software is publicly available, you should submit the
 ``package.py`` for it as a pull request to the main Spack GitHub

lib/spack/docs/conf.py

@@ -1,3 +1,4 @@
+# flake8: noqa
 ##############################################################################
 # Copyright (c) 2013, Lawrence Livermore National Security, LLC.
 # Produced at the Lawrence Livermore National Laboratory.
@@ -47,11 +48,12 @@
 # documentation root, use os.path.abspath to make it absolute, like shown here.
 sys.path.insert(0, os.path.abspath('exts'))
 sys.path.insert(0, os.path.abspath('../external'))
+sys.path.append(os.path.abspath('../spack'))
 
 # Add the Spack bin directory to the path so that we can use its output in docs.
 spack_root = '../../..'
 os.environ['SPACK_ROOT'] = spack_root
-os.environ['PATH'] += os.pathsep + '$SPACK_ROOT/bin'
+os.environ['PATH'] += '%s%s/bin' % (os.pathsep, spack_root)
 
 # Get the spack version for use in the docs
 spack_version =  subprocess.Popen(
@@ -82,6 +84,27 @@
     for cmd in command_names:
         index.write('   * :ref:`%s`\n' % cmd)
 
+#
+# Exclude everything in spack.__all__ from indexing.  All of these
+# symbols are imported from elsewhere in spack; their inclusion in
+# __all__ simply allows package authors to use `from spack import *`.
+# Excluding them ensures they're only documented in their "real" module.
+#
+# 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
+handling_spack = False
+for line in fileinput.input('spack.rst', inplace=1):
+    if handling_spack:
+        if not line.startswith('    :noindex:'):
+            print '    :noindex: %s' % ' '.join(spack.__all__)
+        handling_spack = False
+
+    if line.startswith('.. automodule::'):
+        handling_spack = (line == '.. automodule:: spack\n')
+
+    print line,
 
 # Set an environment variable so that colify will print output like it would to
 # a terminal.

lib/spack/docs/configuration.rst

@@ -1,14 +1,18 @@
 .. _configuration:
 
+=============
 Configuration
-===================================
+=============
 
 .. _temp-space:
 
+---------------
 Temporary space
-----------------------------
+---------------
 
-.. warning:: Temporary space configuration will eventually be moved to
+.. warning::
+
+   Temporary space configuration will eventually be moved to
    configuration files, but currently these settings are in
    ``lib/spack/spack/__init__.py``
 
@@ -55,8 +59,10 @@ directory is.
 
 .. _sec-external_packages:
 
+-----------------
 External Packages
-----------------------------
+-----------------
+
 Spack can be configured to use externally-installed
 packages rather than building its own packages. This may be desirable
 if machines ship with system packages, such as a customized MPI
@@ -126,9 +132,11 @@ The ``buildable`` does not need to be paired with external packages.
 It could also be used alone to forbid packages that may be
 buggy or otherwise undesirable.
 
+.. _concretization-preferences:
 
+--------------------------
 Concretization Preferences
---------------------------------
+--------------------------
 
 Spack can be configured to prefer certain compilers, package
 versions, depends_on, and variants during concretization.
@@ -136,10 +144,9 @@ The preferred configuration can be controlled via the
 ``~/.spack/packages.yaml`` file for user configuations, or the
 ``etc/spack/packages.yaml`` site configuration.
 
-
 Here's an example packages.yaml file that sets preferred packages:
 
-.. code-block:: sh
+.. code-block:: yaml
 
    packages:
      opencv:
@@ -152,7 +159,6 @@ Here's an example packages.yaml file that sets preferred packages:
        providers:
          mpi: [mvapich, mpich, openmpi]
 
-
 At a high level, this example is specifying how packages should be
 concretized.  The opencv package should prefer using gcc 4.9 and
 be built with debug options.  The gperftools package should prefer version
@@ -185,9 +191,9 @@ concretization rules.  A provider lists a value that packages may
 ``depend_on`` (e.g, mpi) and a list of rules for fulfilling that
 dependency.
 
-
+---------
 Profiling
-------------------
+---------
 
 Spack has some limited built-in support for profiling, and can report
 statistics using standard Python timing tools.  To use this feature,
@@ -195,40 +201,14 @@ supply ``-p`` to Spack on the command line, before any subcommands.
 
 .. _spack-p:
 
-``spack -p``
+^^^^^^^^^^^^^^^^^^^
-~~~~~~~~~~~~~~~~~
+``spack --profile``
+^^^^^^^^^^^^^^^^^^^
 
-``spack -p`` output looks like this:
+``spack --profile`` output looks like this:
 
-.. code-block:: sh
+.. command-output:: spack --profile graph dyninst
-
+   :ellipsis: 25
-   $ spack -p graph dyninst
-   o  dyninst
-   |\
-   | |\
-   | o |  libdwarf
-   |/ /
-   o |  libelf
-    /
-   o  boost
-
-         307670 function calls (305943 primitive calls) in 0.127 seconds
-
-   Ordered by: internal time
-
-   ncalls  tottime  percall  cumtime  percall filename:lineno(function)
-      853    0.021    0.000    0.066    0.000 inspect.py:472(getmodule)
-    51197    0.011    0.000    0.018    0.000 inspect.py:51(ismodule)
-    73961    0.010    0.000    0.010    0.000 {isinstance}
-     1762    0.006    0.000    0.053    0.000 inspect.py:440(getsourcefile)
-    32075    0.006    0.000    0.006    0.000 {hasattr}
-     1760    0.004    0.000    0.004    0.000 {posix.stat}
-     2240    0.004    0.000    0.004    0.000 {posix.lstat}
-     2602    0.004    0.000    0.011    0.000 inspect.py:398(getfile)
-      771    0.004    0.000    0.077    0.000 inspect.py:518(findsource)
-     2656    0.004    0.000    0.004    0.000 {method 'match' of '_sre.SRE_Pattern' objects}
-    30772    0.003    0.000    0.003    0.000 {method 'get' of 'dict' objects}
-    ...
 
 The bottom of the output shows the top most time consuming functions,
 slowest on top.  The profiling support is from Python's built-in tool,

lib/spack/docs/developer_guide.rst

@@ -1,7 +1,8 @@
 .. _developer_guide:
 
+===============
 Developer Guide
-=====================
+===============
 
 This guide is intended for people who want to work on Spack itself.
 If you just want to develop packages, see the :ref:`packaging-guide`.
@@ -11,8 +12,9 @@ It is assumed that you've read the :ref:`basic-usage` and
 concepts discussed there.  If you're not, we recommend reading those
 first.
 
+--------
 Overview
------------------------
+--------
 
 Spack is designed with three separate roles in mind:
 
@@ -63,12 +65,14 @@ building the software off to the package object.  The rest of this
 document describes all the pieces that come together to make that
 happen.
 
-
+-------------------
 Directory Structure
--------------------------
+-------------------
 
 So that you can familiarize yourself with the project, we'll start
-with a high level view of Spack's directory structure::
+with a high level view of Spack's directory structure:
+
+.. code-block:: none
 
    spack/                  <- installation root
       bin/
@@ -107,31 +111,29 @@ Spack is designed so that it could live within a `standard UNIX
 directory hierarchy <http://linux.die.net/man/7/hier>`_, so ``lib``,
 ``var``, and ``opt`` all contain a ``spack`` subdirectory in case
 Spack is installed alongside other software.  Most of the interesting
-parts of Spack live in ``lib/spack``.  Files under ``var`` are created
+parts of Spack live in ``lib/spack``.
-as needed, so there is no ``var`` directory when you initially clone
-Spack from the repository.
 
 Spack has *one* directory layout and there is no install process.
-version and the source code.  Most Python programs don't look like
+Most Python programs don't look like this (they use distutils, ``setup.py``,
-this (they use distutils, ``setup.py``, etc.) but we wanted to make
+etc.) but we wanted to make Spack *very* easy to use.  The simple layout
-Spack *very* easy to use.  The simple layout spares users from the
+spares users from the need to install Spack into a Python environment.
-need to install Spack into a Python environment.  Many users don't
+Many users don't have write access to a Python installation, and installing
-have write access to a Python installation, and installing an entire
+an entire new instance of Python to bootstrap Spack would be very complicated.
-new instance of Python to bootstrap Spack would be very complicated.
 Users should not have to install install a big, complicated package to
 use the thing that's supposed to spare them from the details of big,
 complicated packages.  The end result is that Spack works out of the
 box: clone it and add ``bin`` to your PATH and you're ready to go.
 
-
+--------------
 Code Structure
--------------------------
+--------------
 
 This section gives an overview of the various Python modules in Spack,
 grouped by functionality.
 
+^^^^^^^^^^^^^^^^^^^^^^^
 Package-related modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.package`
   Contains the :class:`Package <spack.package.Package>` class, which
@@ -158,9 +160,9 @@ Package-related modules
   decorator, which allows :ref:`multimethods <multimethods>` in
   packages.
 
-
+^^^^^^^^^^^^^^^^^^^^
 Spec-related modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^^
 
 :mod:`spack.spec`
   Contains :class:`Spec <spack.spec.Spec>` and :class:`SpecParser
@@ -208,9 +210,9 @@ Spec-related modules
      Not yet implemented.  Should eventually have architecture
      descriptions for cross-compiling.
 
-
+^^^^^^^^^^^^^^^^^
 Build environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 :mod:`spack.stage`
   Handles creating temporary directories for builds.
@@ -224,15 +226,17 @@ Build environment
   Create more implementations of this to change the hierarchy and
   naming scheme in ``$spack_prefix/opt``
 
+^^^^^^^^^^^^^^^^^
 Spack Subcommands
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^
 
 :mod:`spack.cmd`
   Each module in this package implements a Spack subcommand.  See
   :ref:`writing commands <writing-commands>` for details.
 
+^^^^^^^^^^
 Unit tests
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^
 
 :mod:`spack.test`
   Implements Spack's test suite.  Add a module and put its name in
@@ -242,8 +246,9 @@ Unit tests
   This is a fake package hierarchy used to mock up packages for
   Spack's test suite.
 
+^^^^^^^^^^^^^
 Other Modules
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
 :mod:`spack.globals`
   Includes global settings for Spack.  the default policy classes for
@@ -269,16 +274,15 @@ Other Modules
   :class:`SpackError <spack.error.SpackError>`, the base class for
   Spack's exception hierarchy.
 
-
+------------
 Spec objects
--------------------------
+------------
 
+---------------
 Package objects
--------------------------
+---------------
 
-
+Most spack commands look something like this:
-Most spack commands
-look something like this:
 
 #. Parse an abstract spec (or specs) from the command line,
 #. *Normalize* the spec based on information in package files,
@@ -286,34 +290,37 @@ look something like this:
 #. Instantiate a package based on the spec, and
 #. Call methods (e.g., ``install()``) on the package object.
 
-
-
 The information in Package files is used at all stages in this
 process.
 
+Conceptually, packages are overloaded.  They contain:
 
-Conceptually, packages are overloaded.  They contain
+-------------
-
 Stage objects
--------------------------
+-------------
 
 .. _writing-commands:
 
+----------------
 Writing commands
--------------------------
+----------------
 
+----------
 Unit tests
--------------------------
+----------
 
+------------
 Unit testing
--------------------------
+------------
-
 
+------------------
 Developer commands
--------------------------
+------------------
 
+^^^^^^^^^^^^^
 ``spack doc``
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^
 
+^^^^^^^^^^^^^^
 ``spack test``
-~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^

lib/spack/docs/features.rst

@@ -1,29 +1,32 @@
+================
 Feature overview
-==================
+================
 
 This is a high-level overview of features that make Spack different
 from other `package managers
 <http://en.wikipedia.org/wiki/Package_management_system>`_ and `port
 systems <http://en.wikipedia.org/wiki/Ports_collection>`_.
 
+---------------------------
 Simple package installation
-----------------------------
+---------------------------
 
 Installing the default version of a package is simple. This will install
 the latest version of the ``mpileaks`` package and all of its dependencies:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ spack install mpileaks
 
+--------------------------------
 Custom versions & configurations
--------------------------------------------
+--------------------------------
 
 Spack allows installation to be customized.  Users can specify the
 version, build compiler, compile-time options, and cross-compile
 platform, all on the command line.
 
-.. code-block:: sh
+.. code-block:: console
 
    # Install a particular version by appending @
    $ spack install mpileaks@1.1.2
@@ -47,37 +50,39 @@ Users can specify as many or few options as they care about. Spack
 will fill in the unspecified values with sensible defaults. The two listed
 syntaxes for variants are identical when the value is boolean.
 
-
+----------------------
 Customize dependencies
--------------------------------------
+----------------------
 
 Spack allows *dependencies* of a particular installation to be
 customized extensively.  Suppose that ``mpileaks`` depends indirectly
 on ``libelf`` and ``libdwarf``.  Using ``^``, users can add custom
 configurations for the dependencies:
 
-.. code-block:: sh
+.. code-block:: console
 
    # Install mpileaks and link it with specific versions of libelf and libdwarf
    $ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug ^libelf@0.8.12 ^libdwarf@20130729+debug
 
-
+------------------------
 Non-destructive installs
--------------------------------------
+------------------------
 
 Spack installs every unique package/dependency configuration into its
 own prefix, so new installs will not break existing ones.
 
+-------------------------------
 Packages can peacefully coexist
--------------------------------------
+-------------------------------
 
 Spack avoids library misconfiguration by using ``RPATH`` to link
 dependencies.  When a user links a library or runs a program, it is
 tied to the dependencies it was built with, so there is no need to
 manipulate ``LD_LIBRARY_PATH`` at runtime.
 
+-------------------------
 Creating packages is easy
--------------------------------------
+-------------------------
 
 To create a new packages, all Spack needs is a URL for the source
 archive.  The ``spack create`` command will create a boilerplate
@@ -86,7 +91,7 @@ in pure Python.
 
 For example, this command:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ spack create http://www.mr511.de/software/libelf-0.8.13.tar.gz
 
@@ -96,16 +101,26 @@ creates a simple python file:
 
    from spack import *
 
+
    class Libelf(Package):
-       homepage = "http://www.example.com/"
+       """FIXME: Put a proper description of your package here."""
+
+       # FIXME: Add a proper url for your package's homepage here.
+       homepage = "http://www.example.com"
        url      = "http://www.mr511.de/software/libelf-0.8.13.tar.gz"
 
        version('0.8.13', '4136d7b4c04df68b686570afa26988ac')
 
-       def install(self, prefix):
+       # FIXME: Add dependencies if required.
-           configure("--prefix=%s" % prefix)
+       # depends_on('foo')
+
+       def install(self, spec, prefix):
+           # FIXME: Modify the configure line to suit your build system here.
+           configure('--prefix={0}'.format(prefix))
+
+           # FIXME: Add logic to build and install here.
            make()
-           make("install")
+           make('install')
 
 It doesn't take much python coding to get from there to a working
 package:

lib/spack/docs/getting_started.rst

@@ -1,13 +1,15 @@
+===============
 Getting Started
-====================
+===============
 
+--------
 Download
---------------------
+--------
 
 Getting spack is easy.  You can clone it from the `github repository
 <https://github.com/llnl/spack>`_ using this command:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ git clone https://github.com/llnl/spack.git
 
@@ -16,7 +18,7 @@ full path to this directory is in the ``SPACK_ROOT`` environment
 variable.  Add ``$SPACK_ROOT/bin`` to your path and you're ready to
 go:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ export PATH=$SPACK_ROOT/bin:$PATH
    $ spack install libelf
@@ -24,9 +26,10 @@ go:
 For a richer experience, use Spack's `shell support
 <http://software.llnl.gov/spack/basic_usage.html#environment-modules>`_:
 
-.. code-block:: sh
+.. code-block:: console
 
    # For bash users
+   $ export SPACK_ROOT=/path/to/spack
    $ . $SPACK_ROOT/share/spack/setup-env.sh
 
    # For tcsh or csh users (note you must set SPACK_ROOT)
@@ -35,8 +38,9 @@ For a richer experience, use Spack's `shell support
 
 This automatically adds Spack to your ``PATH``.
 
+------------
 Installation
---------------------
+------------
 
 You don't need to install Spack; it's ready to run as soon as you
 clone it from git.
@@ -45,7 +49,7 @@ You may want to run it out of a prefix other than the git repository
 you cloned.  The ``spack bootstrap`` command provides this
 functionality.  To install spack in a new directory, simply type:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ spack bootstrap /my/favorite/prefix
 

lib/spack/docs/index.rst

@@ -3,8 +3,9 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
+===================
 Spack Documentation
-=================================
+===================
 
 Spack is a package management tool designed to support multiple
 versions and configurations of software on a wide variety of platforms
@@ -27,7 +28,7 @@ Get spack from the `github repository
 <https://github.com/llnl/spack>`_ and install your first
 package:
 
-.. code-block:: sh
+.. code-block:: console
 
    $ git clone https://github.com/llnl/spack.git
    $ cd spack/bin
@@ -36,8 +37,9 @@ package:
 If you're new to spack and want to start using it, see :doc:`getting_started`,
 or refer to the full manual below.
 
+-----------------
 Table of Contents
----------------------
+-----------------
 
 .. toctree::
    :maxdepth: 2
@@ -54,6 +56,7 @@ Table of Contents
    package_list
    API Docs <spack>
 
+==================
 Indices and tables
 ==================
 

lib/spack/docs/mirrors.rst

@@ -1,7 +1,8 @@
 .. _mirrors:
 
+=======
 Mirrors
-============================
+=======
 
 Some sites may not have access to the internet for fetching packages.
 These sites will need a local repository of tarballs from which they
@@ -10,7 +11,9 @@ mirror is a URL that points to a directory, either on the local
 filesystem or on some server, containing tarballs for all of Spack's
 packages.
 
-Here's an example of a mirror's directory structure::
+Here's an example of a mirror's directory structure:
+
+.. code-block:: none
 
    mirror/
        cmake/
@@ -51,25 +54,14 @@ contains tarballs for each package, named after each package.
 
 .. _spack-mirror:
 
+----------------
 ``spack mirror``
-----------------------------
+----------------
 
 Mirrors are managed with the ``spack mirror`` command.  The help for
-``spack mirror`` looks like this::
+``spack mirror`` looks like this:
 
-    $ spack mirror -h
+.. command-output:: spack help mirror
-    usage: spack mirror [-h] SUBCOMMAND ...
-
-    positional arguments:
-      SUBCOMMAND
-        create           Create a directory to be used as a spack mirror, and fill
-                         it with package archives.
-        add              Add a mirror to Spack.
-        remove           Remove a mirror by name.
-        list             Print out available mirrors to the console.
-
-    optional arguments:
-      -h, --help         show this help message and exit
 
 The ``create`` command actually builds a mirror by fetching all of its
 packages from the internet and checksumming them.
@@ -79,8 +71,9 @@ control the URL(s) from which Spack downloads its packages.
 
 .. _spack-mirror-create:
 
+-----------------------
 ``spack mirror create``
-----------------------------
+-----------------------
 
 You can create a mirror using the ``spack mirror create`` command, assuming
 you're on a machine where you can access the internet.
@@ -89,8 +82,7 @@ The command will iterate through all of Spack's packages and download
 the safe ones into a directory structure like the one above.  Here is
 what it looks like:
 
-
+.. code-block:: console
-.. code-block:: bash
 
    $ spack mirror create libelf libdwarf
    ==> Created new mirror in spack-mirror-2014-06-24
@@ -124,25 +116,31 @@ what it looks like:
 Once this is done, you can tar up the ``spack-mirror-2014-06-24`` directory and
 copy it over to the machine you want it hosted on.
 
+^^^^^^^^^^^^^^^^^^^
 Custom package sets
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^^^^^^^^
 
 Normally, ``spack mirror create`` downloads all the archives it has
 checksums for.  If you want to only create a mirror for a subset of
 packages, you can do that by supplying a list of package specs on the
 command line after ``spack mirror create``.  For example, this
-command::
+command:
+
+.. code-block:: console
 
    $ spack mirror create libelf@0.8.12: boost@1.44:
 
 Will create a mirror for libelf versions greater than or equal to
 0.8.12 and boost versions greater than or equal to 1.44.
 
+^^^^^^^^^^^^
 Mirror files
-~~~~~~~~~~~~~~~~~~~~~~~
+^^^^^^^^^^^^
 
 If you have a *very* large number of packages you want to mirror, you
-can supply a file with specs in it, one per line::
+can supply a file with specs in it, one per line:
+
+.. code-block:: console
 
    $ cat specs.txt
    libdwarf
@@ -158,12 +156,15 @@ your site.
 
 .. _spack-mirror-add:
 
+--------------------
 ``spack mirror add``
-----------------------------
+--------------------
 
 Once you have a mirror, you need to let spack know about it.  This is
 relatively simple.  First, figure out the URL for the mirror.  If it's
-a file, you can use a file URL like this one::
+a file, you can use a file URL like this one:
+
+.. code-block:: none
 
    file:///Users/gamblin2/spack-mirror-2014-06-24
 
@@ -175,7 +176,7 @@ web server, you could use a URL like this one:
 Spack will use the URL as the root for all of the packages it fetches.
 You can tell your Spack installation to use that mirror like this:
 
-.. code-block:: bash
+.. code-block:: console
 
    $ spack mirror add local_filesystem file:///Users/gamblin2/spack-mirror-2014-06-24
 
@@ -183,29 +184,38 @@ Each mirror has a name so that you can refer to it again later.
 
 .. _spack-mirror-list:
 
+---------------------
 ``spack mirror list``
-----------------------------
+---------------------
 
-To see all the mirrors Spack knows about, run ``spack mirror list``::
+To see all the mirrors Spack knows about, run ``spack mirror list``:
+
+.. code-block:: console
 
    $ spack mirror list
    local_filesystem    file:///Users/gamblin2/spack-mirror-2014-06-24
 
 .. _spack-mirror-remove:
 
+-----------------------
 ``spack mirror remove``
-----------------------------
+-----------------------
 
-To remove a mirror by name::
+To remove a mirror by name, run:
+
+.. code-block:: console
 
    $ spack mirror remove local_filesystem
    $ spack mirror list
    ==> No mirrors configured.
 
+-----------------
 Mirror precedence
-----------------------------
+-----------------
 
-Adding a mirror really adds a line in ``~/.spack/mirrors.yaml``::
+Adding a mirror really adds a line in ``~/.spack/mirrors.yaml``:
+
+.. code-block:: yaml
 
    mirrors:
      local_filesystem: file:///Users/gamblin2/spack-mirror-2014-06-24
@@ -217,8 +227,9 @@ search the topmost mirror first and the bottom-most mirror last.
 
 .. _caching:
 
+-------------------
 Local Default Cache
-----------------------------
+-------------------
 
 Spack caches resources that are downloaded as part of installs. The cache is
 a valid spack mirror: it uses the same directory structure and naming scheme

lib/spack/spack/build_environment.py

@@ -476,14 +476,12 @@ def setup_package(pkg, dirty=False):
 def fork(pkg, function, dirty=False):
     """Fork a child process to do part of a spack build.
 
-    Arguments:
+    :param pkg: pkg whose environemnt we should set up the forked process for.
+    :param function: arg-less function to run in the child process.
+    :param dirty: If True, do NOT clean the environment before building.
 
-    pkg -- pkg whose environemnt we should set up the
+    Usage::
-           forked process for.
-    function -- arg-less function to run in the child process.
-    dirty -- If True, do NOT clean the environment before building.
 
-    Usage:
        def child_fun():
            # do stuff
        build_env.fork(pkg, child_fun)
@@ -498,6 +496,7 @@ def child_fun():
     well. If things go well, the child exits and the parent
     carries on.
     """
+
     try:
         pid = os.fork()
     except OSError as e:

lib/spack/spack/cmd/package_list.py

@@ -32,8 +32,8 @@
 
 def github_url(pkg):
     """Link to a package file on github."""
-    url = "https://github.com/llnl/spack/blob/master/var/spack/packages/%s/package.py"
+    url = "https://github.com/LLNL/spack/blob/develop/var/spack/repos/builtin/packages/{0}/package.py"
-    return (url % pkg.name)
+    return url.format(pkg.name)
 
 
 def rst_table(elts):
@@ -51,35 +51,41 @@ def print_rst_package_list():
 
     print ".. _package-list:"
     print
+    print "============"
     print "Package List"
-    print "=================="
+    print "============"
-
+    print
     print "This is a list of things you can install using Spack.  It is"
     print "automatically generated based on the packages in the latest Spack"
     print "release."
     print
-
     print "Spack currently has %d mainline packages:" % len(pkgs)
     print
     print rst_table("`%s`_" % p for p in pkg_names)
     print
-    print "-----"
 
     # Output some text for each package.
     for pkg in pkgs:
+        print "-----"
         print
         print ".. _%s:" % pkg.name
         print
+        # Must be at least 2 long, breaks for single letter packages like R.
+        print "-" * max(len(pkg.name), 2)
         print pkg.name
-        print "-" * len(pkg.name)
+        print "-" * max(len(pkg.name), 2)
-        print "Links:"
+        print
+        print "Homepage:"
         print "  * `%s <%s>`__" % (cgi.escape(pkg.homepage), pkg.homepage)
+        print
+        print "Spack package:"
         print "  * `%s/package.py <%s>`__" % (pkg.name, github_url(pkg))
         print
         if pkg.versions:
             print "Versions:"
             print "  " + ", ".join(str(v) for v in
                                    reversed(sorted(pkg.versions)))
+            print
 
         for deptype in spack.alldeps:
             deps = pkg.dependencies_of_type(deptype)
@@ -92,7 +98,6 @@ def print_rst_package_list():
         print "Description:"
         print pkg.format_doc(indent=2)
         print
-        print "-----"
 
 
 def package_list(parser, args):

lib/spack/spack/compilers/clang.py

@@ -83,12 +83,11 @@ def default_version(cls, comp):
             Target: x86_64-unknown-linux-gnu
             Thread model: posix
 
-          On Mac OS X, it looks like this:
+        On Mac OS X, it looks like this::
 
             Apple LLVM version 7.0.2 (clang-700.1.81)
             Target: x86_64-apple-darwin15.2.0
             Thread model: posix
-
         """
         if comp not in cpr._version_cache:
             compiler = Executable(comp)

lib/spack/spack/config.py

@@ -24,8 +24,9 @@
 ##############################################################################
 """This module implements Spack's configuration file handling.
 
+=========================
 Configuration file scopes
-===============================
+=========================
 
 When Spack runs, it pulls configuration data from several config
 directories, each of which contains configuration files.  In Spack,
@@ -35,15 +36,16 @@
    ``$(prefix)/etc/spack/``.
 
 2. ``user``: Spack next loads per-user configuration options from
-    ~/.spack/.
+   ``~/.spack/``.
 
 Spack may read configuration files from both of these locations.  When
 configurations conflict, the user config options take precedence over
 the site configurations.  Each configuration directory may contain
 several configuration files, such as compilers.yaml or mirrors.yaml.
 
+=========================
 Configuration file format
-===============================
+=========================
 
 Configuration files are formatted using YAML syntax.  This format is
 implemented by libyaml (included with Spack as an external module),
@@ -63,13 +65,13 @@
             cc: /usr/local/bin/mpixlc
             ...
 
-In this example, entries like ''compilers'' and ''xlc@12.1'' are used to
+In this example, entries like "compilers" and "xlc@12.1" are used to
 categorize entries beneath them in the tree.  At the root of the tree,
-entries like ''cc'' and ''cxx'' are specified as name/value pairs.
+entries like "cc" and "cxx" are specified as name/value pairs.
 
 ``config.get_config()`` returns these trees as nested dicts, but it
 strips the first level off.  So, ``config.get_config('compilers')``
-would return something like this for the above example:
+would return something like this for the above example::
 
    { 'chaos_5_x86_64_ib' :
        { 'gcc@4.4.7' :
@@ -84,8 +86,9 @@
 Likewise, the ``mirrors.yaml`` file's first line must be ``mirrors:``,
 but ``get_config()`` strips that off too.
 
+==========
 Precedence
-===============================
+==========
 
 ``config.py`` routines attempt to recursively merge configuration
 across scopes.  So if there are ``compilers.py`` files in both the
@@ -99,7 +102,7 @@
 
 Sometimes, it is useful to *completely* override a site setting with a
 user one.  To accomplish this, you can use *two* colons at the end of
-a key in a configuration file.  For example, this:
+a key in a configuration file.  For example, this::
 
      compilers::
        chaos_5_x86_64_ib:
@@ -115,8 +118,8 @@
 
 Will make Spack take compilers *only* from the user configuration, and
 the site configuration will be ignored.
-
 """
+
 import copy
 import os
 import re

lib/spack/spack/directives.py

@@ -288,8 +288,7 @@ def variant(pkg, name, default=False, description=""):
 
 @directive('resources')
 def resource(pkg, **kwargs):
-    """
+    """Define an external resource to be fetched and staged when building the
-    Define an external resource to be fetched and staged when building the
     package. Based on the keywords present in the dictionary the appropriate
     FetchStrategy will be used for the resource. Resources are fetched and
     staged in their own folder inside spack stage area, and then moved into

lib/spack/spack/environment.py

@@ -261,17 +261,14 @@ def apply_modifications(self):
 
     @staticmethod
     def from_sourcing_files(*args, **kwargs):
-        """
+        """Creates an instance of EnvironmentModifications that, if executed,
-        Creates an instance of EnvironmentModifications that, if executed,
         has the same effect on the environment as sourcing the files passed as
         parameters
 
-        Args:
+        :param \*args: list of files to be sourced
-            *args: list of files to be sourced
+        :rtype: instance of EnvironmentModifications
-
-        Returns:
-            instance of EnvironmentModifications
         """
+
         env = EnvironmentModifications()
         # Check if the files are actually there
         if not all(os.path.isfile(file) for file in args):

lib/spack/spack/mirror.py

@@ -123,17 +123,18 @@ def create(path, specs, **kwargs):
     package archives.
 
     Arguments:
-         path    Path to create a mirror directory hierarchy in.
+        path: Path to create a mirror directory hierarchy in.
-         specs   Any package versions matching these specs will be added
+        specs: Any package versions matching these specs will be added \
             to the mirror.
 
     Keyword args:
         no_checksum: If True, do not checkpoint when fetching (default False)
-         num_versions: Max number of versions to fetch per spec,
+        num_versions: Max number of versions to fetch per spec, \
             if spec is ambiguous (default is 0 for all of them)
 
     Return Value:
         Returns a tuple of lists: (present, mirrored, error)
+
         * present:  Package specs that were already present.
         * mirrored: Package specs that were successfully mirrored.
         * error:    Package specs that failed to mirror due to some error.

lib/spack/spack/package.py

@@ -84,9 +84,9 @@ class Package(object):
     with the package itself.  Packages are written in pure python.
 
     Packages are all submodules of spack.packages.  If spack is installed
-    in $prefix, all of its python files are in $prefix/lib/spack.  Most
+    in ``$prefix``, all of its python files are in ``$prefix/lib/spack``.
-    of them are in the spack module, so all the packages live in
+    Most of them are in the spack module, so all the packages live in
-    $prefix/lib/spack/spack/packages.
+    ``$prefix/lib/spack/spack/packages``.
 
     All you have to do to create a package is make a new subclass of Package
     in this directory.  Spack automatically scans the python files there
@@ -95,7 +95,7 @@ class Package(object):
     **An example package**
 
     Let's look at the cmake package to start with.  This package lives in
-    $prefix/lib/spack/spack/packages/cmake.py:
+    ``$prefix/var/spack/repos/builtin/packages/cmake/package.py``:
 
     .. code-block:: python
 
@@ -118,19 +118,21 @@ def install(self, spec, prefix):
     1. The module name, ``cmake``.
 
        * User will refers to this name, e.g. 'spack install cmake'.
-       * Corresponds to the name of the file, 'cmake.py', and it can
+       * It can include ``_``, ``-``, and numbers (it can even start with a
-         include ``_``, ``-``, and numbers (it can even start with a
          number).
 
     2. The class name, "Cmake".  This is formed by converting `-` or
        ``_`` in the module name to camel case.  If the name starts with
        a number, we prefix the class name with ``_``. Examples:
 
+          ===========  ==========
           Module Name  Class Name
+          ===========  ==========
           foo_bar      FooBar
           docbook-xml  DocbookXml
           FooBar       Foobar
           3proxy       _3proxy
+          ===========  ==========
 
         The class name is what spack looks for when it loads a package module.
 
@@ -139,16 +141,16 @@ def install(self, spec, prefix):
     Aside from proper naming, here is the bare minimum set of things you
     need when you make a package:
 
-    homepage
+    homepage:
         informational URL, so that users know what they're
         installing.
 
-    url or url_for_version(self, version)
+    url or url_for_version(self, version):
       If url, then the URL of the source archive that spack will fetch.
       If url_for_version(), then a method returning the URL required
       to fetch a particular version.
 
-    install()
+    install():
         This function tells spack how to build and install the
         software it downloaded.
 
@@ -156,13 +158,13 @@ def install(self, spec, prefix):
 
     You can also optionally add these attributes, if needed:
 
-        list_url
+        list_url:
             Webpage to scrape for available version strings. Default is the
             directory containing the tarball; use this if the default isn't
             correct so that invoking 'spack versions' will work for this
             package.
 
-        url_version(self, version)
+        url_version(self, version):
             When spack downloads packages at particular versions, it just
             converts version to string with str(version).  Override this if
             your package needs special version formatting in its URL.  boost
@@ -179,12 +181,15 @@ def install(self, spec, prefix):
 
     **spack create**
 
-    Most software comes in nicely packaged tarballs, like this one:
+    Most software comes in nicely packaged tarballs, like this one
+
     http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz
+
     Taking a page from homebrew, spack deduces pretty much everything it
-    needs to know from the URL above.  If you simply type this:
+    needs to know from the URL above.  If you simply type this::
 
         spack create http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz
+
     Spack will download the tarball, generate an md5 hash, figure out the
     version and the name of the package from the URL, and create a new
     package file for you with all the names and attributes set correctly.
@@ -216,7 +221,6 @@ class Stackwalker(Package):
     you can just run configure or cmake without any additional arguments and
     it will find the dependencies automatically.
 
-
     **The Install Function**
 
     The install function is designed so that someone not too terribly familiar
@@ -241,13 +245,12 @@ class Stackwalker(Package):
     add_commands_to_module() function in this class. This is where most of
     them are created and set on the module.
 
-
     **Parallel Builds**
 
     By default, Spack will run make in parallel when you run make() in your
     install function.  Spack figures out how many cores are available on
-    your system and runs make with -j<cores>.  If you do not want this behavior,
+    your system and runs make with -j<cores>.  If you do not want this
-    you can explicitly mark a package not to use parallel make:
+    behavior, you can explicitly mark a package not to use parallel make:
 
     .. code-block:: python
 
@@ -257,14 +260,15 @@ class SomePackage(Package):
            ...
 
     This changes thd default behavior so that make is sequential.  If you still
-    want to build some parts in parallel, you can do this in your install function:
+    want to build some parts in parallel, you can do this in your install
+    function:
 
     .. code-block:: python
 
        make(parallel=True)
 
-    Likewise, if you do not supply parallel = True in your Package, you can keep
+    Likewise, if you do not supply parallel = True in your Package, you can
-    the default parallel behavior and run make like this when you want a
+    keep the default parallel behavior and run make like this when you want a
     sequential build:
 
     .. code-block:: python
@@ -295,14 +299,13 @@ class SomePackage(Package):
        p.do_restage()            # removes the build directory and
                                  # re-expands the archive.
 
-    The convention used here is that a do_* function is intended to be called
+    The convention used here is that a ``do_*`` function is intended to be
-    internally by Spack commands (in spack.cmd).  These aren't for package
+    called internally by Spack commands (in spack.cmd).  These aren't for
-    writers to override, and doing so may break the functionality of the Package
+    package writers to override, and doing so may break the functionality
-    class.
+    of the Package class.
 
     Package creators override functions like install() (all of them do this),
     clean() (some of them do this), and others to provide custom behavior.
-
     """
     #
     # These are default values for instance variables.
@@ -862,19 +865,21 @@ def do_install(self,
         Package implementations should override install() to describe
         their build process.
 
-        Args:
+        :param keep_prefix: Keep install prefix on failure. By default, \
-        keep_prefix -- Keep install prefix on failure. By default, destroys it.
+            destroys it.
-        keep_stage  -- By default, stage is destroyed only if there are no
+        :param keep_stage: By default, stage is destroyed only if there are \
-                       exceptions during build. Set to True to keep the stage
+            no exceptions during build. Set to True to keep the stage
             even with exceptions.
-        ignore_deps -- Don't install dependencies before installing this
+        :param ignore_deps: Don't install dependencies before installing this \
                        package
-        fake        -- Don't really build -- install fake stub files instead.
+        :param fake: Don't really build; install fake stub files instead.
-        skip_patch  -- Skip patch stage of build if True.
+        :param skip_patch: Skip patch stage of build if True.
-        verbose     -- Display verbose build output (by default, suppresses it)
+        :param verbose: Display verbose build output (by default, suppresses \
-        dirty       -- Don't clean the build environment before installing.
+            it)
-        make_jobs   -- Number of make jobs to use for install. Default is ncpus
+        :param dirty: Don't clean the build environment before installing.
-        run_tests   -- Runn tests within the package's install()
+        :param make_jobs: Number of make jobs to use for install. Default is \
+            ncpus
+        :param run_tests: Run tests within the package's install()
         """
         if not self.spec.concrete:
             raise ValueError("Can only install concrete packages: %s."
@@ -1110,13 +1115,13 @@ def setup_environment(self, spack_env, run_env):
     def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
         """Set up the environment of packages that depend on this one.
 
-        This is similar to `setup_environment`, but it is used to
+        This is similar to ``setup_environment``, but it is used to
         modify the compile and runtime environments of packages that
         *depend* on this one. This gives packages like Python and
         others that follow the extension model a way to implement
         common environment or compile-time settings for dependencies.
 
-        By default, this delegates to self.setup_environment()
+        By default, this delegates to ``self.setup_environment()``
 
         Example:
 
@@ -1142,7 +1147,6 @@ def setup_dependent_environment(self, spack_env, run_env, dependent_spec):
 
         This is useful if there are some common steps to installing
         all extensions for a certain package.
-
         """
         self.setup_environment(spack_env, run_env)
 

lib/spack/spack/repository.py

@@ -198,13 +198,17 @@ def remove(self, repo):
 
     def get_repo(self, namespace, default=NOT_PROVIDED):
         """Get a repository by namespace.
-        Arguments
-          namespace
-            Look up this namespace in the RepoPath, and return
-            it if found.
 
-        Optional Arguments
+        Arguments:
-          default
+
+            namespace:
+
+                Look up this namespace in the RepoPath, and return it if found.
+
+        Optional Arguments:
+
+            default:
+
                 If default is provided, return it when the namespace
                 isn't found.  If not, raise an UnknownNamespaceError.
         """

lib/spack/spack/spec.py

@@ -2085,7 +2085,7 @@ def format(self, format_string='$_$@$%@+$+$=', **kwargs):
             $#   7-char prefix of DAG hash with '-' prefix
             $$   $
 
-            You can also use full-string versions, which elide the prefixes:
+        You can also use full-string versions, which elide the prefixes::
 
             ${PACKAGE}       Package name
             ${VERSION}       Version
@@ -2101,17 +2101,17 @@ def format(self, format_string='$_$@$%@+$+$=', **kwargs):
             ${SPACK_INSTALL} The default spack install directory,
                              ${SPACK_PREFIX}/opt
 
-        Optionally you can provide a width, e.g. $20_ for a 20-wide name.
+        Optionally you can provide a width, e.g. ``$20_`` for a 20-wide name.
         Like printf, you can provide '-' for left justification, e.g.
-        $-20_ for a left-justified name.
+        ``$-20_`` for a left-justified name.
 
         Anything else is copied verbatim into the output stream.
 
         *Example:*  ``$_$@$+`` translates to the name, version, and options
         of the package, but no dependencies, arch, or compiler.
 
-        TODO: allow, e.g., $6# to customize short hash length
+        TODO: allow, e.g., ``$6#`` to customize short hash length
-        TODO: allow, e.g., $## for full hash.
+        TODO: allow, e.g., ``$##`` for full hash.
         """
         color = kwargs.get('color', False)
         length = len(format_string)

lib/spack/spack/stage.py

@@ -49,16 +49,14 @@ class Stage(object):
     some source code is downloaded and built before being installed.
     It handles fetching the source code, either as an archive to be
     expanded or by checking it out of a repository.  A stage's
-    lifecycle looks like this:
+    lifecycle looks like this::
 
-    ```
         with Stage() as stage:      # Context manager creates and destroys the
                                     # stage directory
             stage.fetch()           # Fetch a source archive into the stage.
             stage.expand_archive()  # Expand the source archive.
-        <install>               # Build and install the archive. (handled by
+            <install>               # Build and install the archive.
-                                # user of Stage)
+                                    # (handled by user of Stage)
-    ```
 
     When used as a context manager, the stage is automatically
     destroyed if no exception is raised by the context. If an
@@ -66,19 +64,17 @@ class Stage(object):
     destroyed, for potential reuse later.
 
     You can also use the stage's create/destroy functions manually,
-    like this:
+    like this::
 
-    ```
         stage = Stage()
         try:
             stage.create()          # Explicitly create the stage directory.
             stage.fetch()           # Fetch a source archive into the stage.
             stage.expand_archive()  # Expand the source archive.
-        <install>               # Build and install the archive. (handled by
+            <install>               # Build and install the archive.
-                                # user of Stage)
+                                    # (handled by user of Stage)
         finally:
             stage.destroy()         # Explicitly destroy the stage directory.
-    ```
 
     If spack.use_tmp_stage is True, spack will attempt to create
     stages in a tmp directory.  Otherwise, stages are created directly

lib/spack/spack/test/cmd/test_install.py

@@ -30,6 +30,7 @@
 
 import spack
 import spack.cmd
+from spack.cmd import test_install
 
 FILE_REGISTRY = collections.defaultdict(StringIO.StringIO)
 
@@ -51,11 +52,6 @@ def mock_open(filename, mode):
         handle.close()
 
 
-# The use of __import__ is necessary to maintain a name with hyphen (which
-# cannot be an identifier in python)
-test_install = __import__("spack.cmd.test-install", fromlist=['test_install'])
-
-
 class MockSpec(object):
 
     def __init__(self, name, version, hashStr=None):

lib/spack/spack/test/git_fetch.py

@@ -56,6 +56,7 @@ def assert_rev(self, rev):
 
     def try_fetch(self, rev, test_file, args):
         """Tries to:
+
         1. Fetch the repo using a fetch strategy constructed with
            supplied args.
         2. Check if the test_file is in the checked out repository.

lib/spack/spack/test/hg_fetch.py

@@ -52,6 +52,7 @@ def tearDown(self):
 
     def try_fetch(self, rev, test_file, args):
         """Tries to:
+
         1. Fetch the repo using a fetch strategy constructed with
            supplied args.
         2. Check if the test_file is in the checked out repository.

lib/spack/spack/test/mirror.py

@@ -53,6 +53,7 @@ def tearDown(self):
     def set_up_package(self, name, MockRepoClass, url_attr):
         """Set up a mock package to be mirrored.
         Each package needs us to:
+
         1. Set up a mock repo/archive to fetch from.
         2. Point the package's version args at that repo.
         """

lib/spack/spack/test/provider_index.py

@@ -24,7 +24,7 @@
 ##############################################################################
 """Tests for provider index cache files.
 
-Tests assume that mock packages provide this:
+Tests assume that mock packages provide this::
 
   {'blas':   {
        blas: set([netlib-blas, openblas, openblas-with-lapack])},

lib/spack/spack/test/svn_fetch.py

@@ -63,6 +63,7 @@ def get_rev():
 
     def try_fetch(self, rev, test_file, args):
         """Tries to:
+
         1. Fetch the repo using a fetch strategy constructed with
            supplied args.
         2. Check if the test_file is in the checked out repository.

lib/spack/spack/util/pattern.py

@@ -31,15 +31,15 @@ def composite(interface=None, method_list=None, container=list):
     """Returns a class decorator that patches a class adding all the methods
     it needs to be a composite for a given interface.
 
-    :param interface: class exposing the interface to which the composite
+    :param interface: class exposing the interface to which the composite \
-    object must conform. Only non-private and non-special methods will be
+        object must conform. Only non-private and non-special methods will \
-    taken into account
+        be taken into account
 
     :param method_list: names of methods that should be part of the composite
 
-    :param container: container for the composite object (default = list).
+    :param container: container for the composite object (default = list). \
-    Must fulfill the MutableSequence contract. The composite class will expose
+        Must fulfill the MutableSequence contract. The composite class will \
-    the container API to manage object composition
+        expose the container API to manage object composition
 
     :return: class decorator
     """

lib/spack/spack/version.py

@@ -155,11 +155,12 @@ def highest(self):
 
     @coerced
     def satisfies(self, other):
-        """A Version 'satisfies' another if it is at least as specific and has a
+        """A Version 'satisfies' another if it is at least as specific and has
-           common prefix.  e.g., we want gcc@4.7.3 to satisfy a request for
+        a common prefix.  e.g., we want gcc@4.7.3 to satisfy a request for
         gcc@4.7 so that when a user asks to build with gcc@4.7, we can find
         a suitable compiler.
         """
+
         nself = len(self.version)
         nother = len(other.version)
         return nother <= nself and self.version[:nother] == other.version
@@ -388,10 +389,10 @@ def __contains__(self, other):
 
     @coerced
     def satisfies(self, other):
-        """
+        """A VersionRange satisfies another if some version in this range
-        A VersionRange satisfies another if some version in this range
         would satisfy some version in the other range.  To do this it must
         either:
+
         a) Overlap with the other range
         b) The start of this range satisfies the end of the other range.
 
@@ -401,6 +402,7 @@ def satisfies(self, other):
         by 4.7.3.5, etc.
 
         Rationale:
+
         If a user asks for gcc@4.5:4.7, and a package is only compatible with
         gcc@4.7.3:4.8, then that package should be able to build under the
         constraints.  Just using overlaps() would not work here.

share/spack/qa/changed_files

@@ -0,0 +1,31 @@
+#!/usr/bin/env bash
+#
+# Description:
+#     Returns a list of changed files.
+#
+# Usage:
+#     changed_files [<directory> ...]
+#     changed_files [<file> ...]
+#     changed_files ["*.<extension>" ...]
+#
+# Options:
+#     Directories, files, or globs to search for changed files.
+#
+
+# Move to root directory of Spack
+# Allows script to be run from anywhere
+SPACK_ROOT="$(dirname "$0")/../../.."
+cd "$SPACK_ROOT"
+
+# Add changed files that have been committed since branching off of develop
+changed=($(git diff --name-only --find-renames develop... -- "$@"))
+# Add changed files that have been staged but not yet committed
+changed+=($(git diff --name-only --find-renames --cached -- "$@"))
+# Add changed files that are unstaged
+changed+=($(git diff --name-only --find-renames -- "$@"))
+# Add new files that are untracked
+changed+=($(git ls-files --exclude-standard --other -- "$@"))
+
+# Return array
+# Ensure that each file in the array is unique
+printf '%s\n' "${changed[@]}" | sort -u

share/spack/qa/check_dependencies

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+#
+# Description:
+#     Check to see if dependencies are installed.
+#     If not, warn the user and tell them how to
+#     install these dependencies.
+#
+# Usage:
+#     check-deps <dep> ...
+#
+# Options:
+#     One or more dependencies. Must use name of binary.
+
+for dep in "$@"; do
+    if ! which $dep &> /dev/null; then
+        # Map binary name to package name
+        case $dep in
+            sphinx-apidoc|sphinx-build)
+                spack_package=py-sphinx
+                pip_package=sphinx
+                ;;
+            coverage)
+                spack_package=py-coverage
+                pip_package=coverage
+                ;;
+            flake8)
+                spack_package=py-flake8
+                pip_package=flake8
+                ;;
+            git)
+                spack_package=git
+                ;;
+            hg)
+                spack_package=mercurial
+                pip_package=mercurial
+                ;;
+            svn)
+                spack_package=subversion
+                ;;
+            *)
+                spack_package=$dep
+                pip_package=$dep
+                ;;
+        esac
+
+        echo "ERROR: $dep is required to run this script."
+        echo
+
+        if [[ $spack_package ]]; then
+            echo "To install with Spack, run:"
+            echo "    $ spack install $spack_package"
+        fi
+
+        if [[ $pip_package ]]; then
+            echo "To install with pip, run:"
+            echo "    $ pip install $pip_package"
+        fi
+
+        if [[ $spack_package || $pip_package ]]; then
+            echo "Then add the bin directory to your PATH."
+        fi
+
+        exit 1
+    fi
+done
+
+echo "Dependencies found."

share/spack/qa/run-doc-tests

@@ -0,0 +1,43 @@
+#!/usr/bin/env bash
+#
+# Description:
+#     Builds Spack documentation and checks for
+#     possible syntax errors. Treats warnings as
+#     fatal errors.
+#
+# Usage:
+#     run-doc-tests
+#
+# Notes:
+#     Requires sphinx, git, mercurial, and subversion.
+#
+
+QA_DIR="$(dirname "$0")"
+SPACK_ROOT="$QA_DIR/../../.."
+DOC_DIR="$SPACK_ROOT/lib/spack/docs"
+
+# Array of dependencies
+deps=(
+    sphinx-apidoc
+    sphinx-build
+    git
+    hg
+    svn
+)
+
+# Check for dependencies
+"$QA_DIR/check_dependencies" "${deps[@]}" || exit 1
+
+# Add Spack to the PATH.
+export PATH="$SPACK_ROOT/bin:$PATH"
+
+# Move to documentation directory
+# Allows script to be run from anywhere
+cd "$DOC_DIR"
+
+# Cleanup temporary files upon exit or when script is killed
+trap 'make clean --silent' EXIT SIGINT SIGTERM
+
+# Treat warnings as fatal errors
+make SPHINXOPTS=-W
+

share/spack/qa/run-flake8

@@ -1,86 +0,0 @@
-#!/bin/bash
-#
-# This script runs source code style checks on Spack.
-#
-# To run it, you'll need to have the Python flake8 installed locally.
-#
-PYTHONPATH=./lib/spack:$PYTHONPATH
-
-flake8="$(which flake8)"
-if [[ ! $flake8 ]]; then
-    echo "ERROR: flake8 is required to run this script."
-    exit 1
-fi
-
-# Move to Spack root; allows script to be run from anywhere
-cd "$(dirname "$0")/../../.."
-
-# Add changed files that have been committed since branching off of develop
-changed=($(git diff --name-only --find-renames develop... -- '*.py'))
-# Add changed files that have been staged but not yet committed
-changed+=($(git diff --name-only --find-renames --cached -- '*.py'))
-# Add changed files that are unstaged
-changed+=($(git diff --name-only --find-renames -- '*.py'))
-# Add new files that are untracked
-changed+=($(git ls-files --exclude-standard --other -- '*.py'))
-
-# Ensure that each file in the array is unique
-changed=($(printf '%s\n' "${changed[@]}" | sort -u))
-
-function cleanup {
-    # Restore original package files after modifying them.
-    for file in "${changed[@]}"; do
-        if [[ -e "${file}.sbak~" ]]; then
-            mv "${file}.sbak~" "${file}"
-        fi
-    done
-}
-
-# Cleanup temporary files upon exit or when script is killed
-trap cleanup EXIT SIGINT SIGTERM
-
-# Add approved style exemptions to the changed packages.
-for file in "${changed[@]}"; do
-    # Make a backup to restore later
-    cp "$file" "$file.sbak~"
-
-    #
-    # Exemptions for package.py files
-    #
-    if [[ $file = *package.py ]]; then
-        # Exempt lines with urls and descriptions from overlong line errors.
-        perl -i -pe 's/^(\s*homepage\s*=.*)$/\1  # NOQA: ignore=E501/' $file
-        perl -i -pe 's/^(\s*url\s*=.*)$/\1  # NOQA: ignore=E501/' $file
-        perl -i -pe 's/^(\s*version\(.*\).*)$/\1  # NOQA: ignore=E501/' $file
-        perl -i -pe 's/^(\s*variant\(.*\).*)$/\1  # NOQA: ignore=E501/' $file
-        perl -i -pe 's/^(\s*depends_on\(.*\).*)$/\1  # NOQA: ignore=E501/' $file
-        perl -i -pe 's/^(\s*extends\(.*\).*)$/\1  # NOQA: ignore=E501/' $file
-
-        # Exempt '@when' decorated functions from redefinition errors.
-        perl -i -pe 's/^(\s*\@when\(.*\).*)$/\1  # NOQA: ignore=F811/' $file
-    fi
-
-    #
-    # Exemptions for all files
-    #
-    perl -i -pe 's/^(.*(https?|file)\:.*)$/\1  # NOQA: ignore=E501/' $file
-done
-
-if [[ "${changed[@]}" ]]; then
-    echo =======================================================
-    echo  flake8: running flake8 code checks on spack.
-    echo
-    echo  Modified files:
-    echo  "${changed[@]}" | perl -pe 's/^/  /;s/ +/\n  /g'
-    echo =======================================================
-    if flake8 --format pylint "${changed[@]}"; then
-        echo "Flake8 checks were clean."
-    else
-        echo "Flake8 found errors."
-        exit 1
-    fi
-else
-    echo No core framework files modified.
-fi
-
-exit 0

share/spack/qa/run-flake8-tests

@@ -0,0 +1,89 @@
+#!/usr/bin/env bash
+#
+# Description:
+#     Runs source code style checks on Spack.
+#     See $SPACK_ROOT/.flake8 for a list of
+#     approved exceptions.
+#
+# Usage:
+#     run-flake8-tests
+#
+# Notes:
+#     Requires flake8.
+#
+
+QA_DIR="$(dirname "$0")"
+SPACK_ROOT="$QA_DIR/../../.."
+
+# Array of dependencies
+deps=(
+    flake8
+)
+
+# Check for dependencies
+"$QA_DIR/check_dependencies" "${deps[@]}" || exit 1
+
+# Move to root directory of Spack
+# Allows script to be run from anywhere
+cd "$SPACK_ROOT"
+
+# Gather array of changed files
+changed=($("$QA_DIR/changed_files" "*.py"))
+
+# Exit if no Python files were modified
+if [[ ! "${changed[@]}" ]]; then
+    echo "No Python files were modified."
+    exit 0
+fi
+
+function cleanup {
+    # Restore original package files after modifying them.
+    for file in "${changed[@]}"; do
+        if [[ -e "${file}.sbak~" ]]; then
+            mv "${file}.sbak~" "${file}"
+        fi
+    done
+}
+
+# Cleanup temporary files upon exit or when script is killed
+trap cleanup EXIT SIGINT SIGTERM
+
+# Add approved style exemptions to the changed packages.
+for file in "${changed[@]}"; do
+    # Make a backup to restore later
+    cp "$file" "$file.sbak~"
+
+    #
+    # Exemptions for package.py files
+    #
+    if [[ $file = *package.py ]]; then
+        # Exempt lines with urls and descriptions from overlong line errors.
+        perl -i -pe 's/^(\s*homepage\s*=.*)$/\1  # NOQA: ignore=E501/' "$file"
+        perl -i -pe 's/^(\s*url\s*=.*)$/\1  # NOQA: ignore=E501/' "$file"
+        perl -i -pe 's/^(\s*version\(.*\).*)$/\1  # NOQA: ignore=E501/' "$file"
+        perl -i -pe 's/^(\s*variant\(.*\).*)$/\1  # NOQA: ignore=E501/' "$file"
+        perl -i -pe 's/^(\s*depends_on\(.*\).*)$/\1  # NOQA: ignore=E501/' "$file"
+        perl -i -pe 's/^(\s*extends\(.*\).*)$/\1  # NOQA: ignore=E501/' "$file"
+
+        # Exempt '@when' decorated functions from redefinition errors.
+        perl -i -pe 's/^(\s*\@when\(.*\).*)$/\1  # NOQA: ignore=F811/' "$file"
+    fi
+
+    #
+    # Exemptions for all files
+    #
+    perl -i -pe 's/^(.*(https?|file)\:.*)$/\1  # NOQA: ignore=E501/' $file
+done
+
+echo =======================================================
+echo  flake8: running flake8 code checks on spack.
+echo
+echo  Modified files:
+echo  "${changed[@]}" | perl -pe 's/^/  /;s/ +/\n  /g'
+echo =======================================================
+if flake8 --format pylint "${changed[@]}"; then
+    echo "Flake8 checks were clean."
+else
+    echo "Flake8 found errors."
+    exit 1
+fi

share/spack/qa/run-unit-tests

@@ -1,20 +1,46 @@
 #!/usr/bin/env bash
 #
-# This script runs Spack unit tests.
+# Description:
+#     Runs Spack unit tests.
 #
-# It should be executed from the top-level directory of the repo,
+# Usage:
-# e.g.:
+#     run-unit-tests [test ...]
 #
-#    share/spack/qa/run-unit-tests
+# Options:
+#     Optionally add one or more unit tests
+#     to only run these tests.
 #
-# To run it, you'll need to have the Python coverage installed locally.
+# Notes:
+#     Requires coverage, git, mercurial, and subversion.
 #
 
-# Regular spack setup and tests
+QA_DIR="$(dirname "$0")"
-. ./share/spack/setup-env.sh
+SPACK_ROOT="$QA_DIR/../../.."
+
+# Array of dependencies
+deps=(
+    coverage
+    git
+    hg
+    svn
+)
+
+# Check for dependencies
+"$QA_DIR/check_dependencies" "${deps[@]}" || exit 1
+
+# Add Spack to the PATH.
+export PATH="$SPACK_ROOT/bin:$PATH"
+
+# Move to root directory of Spack
+# Allows script to be run from anywhere
+cd "$SPACK_ROOT"
+
+# Run integration tests
+# TODO: should these be separated into a different test suite?
+source "$SPACK_ROOT/share/spack/setup-env.sh"
 spack compilers
 spack config get compilers
 spack install -v libdwarf
 
 # Run unit tests with code coverage
-coverage run bin/spack test
+coverage run bin/spack test "$@"

var/spack/repos/builtin/packages/adios/package.py

@@ -27,11 +27,10 @@
 
 
 class Adios(Package):
-    """
+    """The Adaptable IO System (ADIOS) provides a simple,
-    The Adaptable IO System (ADIOS) provides a simple,
     flexible way for scientists to describe the
     data in their code that may need to be written,
-    read, or processed outside of the running simulation
+    read, or processed outside of the running simulation.
     """
 
     homepage = "http://www.olcf.ornl.gov/center-projects/adios/"

var/spack/repos/builtin/packages/antlr/package.py

@@ -26,6 +26,11 @@
 
 
 class Antlr(Package):
+    """ANTLR (ANother Tool for Language Recognition) is a powerful parser
+    generator for reading, processing, executing, or translating structured
+    text or binary files. It's widely used to build languages, tools, and
+    frameworks. From a grammar, ANTLR generates a parser that can build and
+    walk parse trees."""
 
     homepage = "http://www.antlr.org"
     url      = "https://github.com/antlr/antlr/tarball/v2.7.7"

var/spack/repos/builtin/packages/arpack-ng/package.py

@@ -26,8 +26,7 @@
 
 
 class ArpackNg(Package):
-    """
+    """ARPACK-NG is a collection of Fortran77 subroutines designed to solve large
-    ARPACK-NG is a collection of Fortran77 subroutines designed to solve large
     scale eigenvalue problems.
 
     Important Features:
@@ -53,6 +52,7 @@ class ArpackNg(Package):
 
     arpack-ng is replacing arpack almost everywhere.
     """
+
     homepage = 'https://github.com/opencollab/arpack-ng'
     url = 'https://github.com/opencollab/arpack-ng/archive/3.3.0.tar.gz'
 

var/spack/repos/builtin/packages/asciidoc/package.py

@@ -28,6 +28,7 @@
 class Asciidoc(Package):
     """A presentable text document format for writing articles, UNIX man
     pages and other small to medium sized documents."""
+
     homepage = "http://asciidoc.org"
     url      = "http://downloads.sourceforge.net/project/asciidoc/asciidoc/8.6.9/asciidoc-8.6.9.tar.gz"
 

var/spack/repos/builtin/packages/astyle/package.py

@@ -26,10 +26,10 @@
 
 
 class Astyle(Package):
-    """
+    """A Free, Fast, and Small Automatic Formatter for C, C++, C++/CLI,
-    A Free, Fast, and Small Automatic Formatter for C, C++, C++/CLI,
     Objective-C, C#, and Java Source Code.
     """
+
     homepage = "http://astyle.sourceforge.net/"
     url      = "http://downloads.sourceforge.net/project/astyle/astyle/astyle%202.04/astyle_2.04_linux.tar.gz"
 

var/spack/repos/builtin/packages/caliper/package.py

@@ -26,8 +26,7 @@
 
 
 class Caliper(Package):
-    """
+    """Caliper is a generic context annotation system. It gives programmers the
-    Caliper is a generic context annotation system. It gives programmers the
     ability to provide arbitrary program context information to (performance)
     tools at runtime.
     """

var/spack/repos/builtin/packages/cfitsio/package.py

@@ -26,11 +26,12 @@
 
 
 class Cfitsio(Package):
-    """
+    """CFITSIO is a library of C and Fortran subroutines for reading and writing
-    CFITSIO is a library of C and Fortran subroutines for reading and writing
     data files in FITS (Flexible Image Transport System) data format.
     """
+
     homepage = 'http://heasarc.gsfc.nasa.gov/fitsio/'
+
     version('3.370', 'abebd2d02ba5b0503c633581e3bfa116')
 
     def url_for_version(self, v):

var/spack/repos/builtin/packages/cityhash/package.py

@@ -27,6 +27,8 @@
 
 
 class Cityhash(Package):
+    """CityHash, a family of hash functions for strings."""
+
     homepage = "https://github.com/google/cityhash"
     url      = "https://github.com/google/cityhash"
 

var/spack/repos/builtin/packages/cube/package.py

@@ -22,13 +22,11 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-
 from spack import *
 
 
 class Cube(Package):
-    """
+    """Cube the profile viewer for Score-P and Scalasca profiles. It displays a
-    Cube the profile viewer for Score-P and Scalasca profiles. It displays a
     multi-dimensional performance space consisting of the dimensions:
     - performance metric
     - call path

var/spack/repos/builtin/packages/datamash/package.py

@@ -26,8 +26,7 @@
 
 
 class Datamash(Package):
-    """
+    """GNU datamash is a command-line program which performs basic numeric,
-    GNU datamash is a command-line program which performs basic numeric,
     textual and statistical operations on input textual data files.
     """
 

var/spack/repos/builtin/packages/eigen/package.py

@@ -26,10 +26,8 @@
 
 
 class Eigen(Package):
-    """
+    """Eigen is a C++ template library for linear algebra matrices,
-    Eigen is a C++ template library for linear algebra
+    vectors, numerical solvers, and related algorithms.
-
-    Matrices, vectors, numerical solvers, and related algorithms
     """
 
     homepage = 'http://eigen.tuxfamily.org/'

var/spack/repos/builtin/packages/espresso/package.py

@@ -23,17 +23,16 @@
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
 from spack import *
-
 import os
 
 
 class Espresso(Package):
-    """
+    """QE is an integrated suite of Open-Source computer codes for
-    QE is an integrated suite of Open-Source computer codes for
     electronic-structure calculations and materials modeling at
     the nanoscale. It is based on density-functional theory, plane
     waves, and pseudopotentials.
     """
+
     homepage = 'http://quantum-espresso.org'
     url = 'http://www.qe-forge.org/gf/download/frsrelease/204/912/espresso-5.3.0.tar.gz'
 

var/spack/repos/builtin/packages/gdal/package.py

@@ -26,14 +26,13 @@
 
 
 class Gdal(Package):
-    """
+    """GDAL is a translator library for raster and vector geospatial
-    GDAL is a translator library for raster and vector geospatial
     data formats that is released under an X/MIT style Open Source
     license by the Open Source Geospatial Foundation. As a library,
     it presents a single raster abstract data model and vector
     abstract data model to the calling application for all supported
     formats. It also comes with a variety of useful command line
-    utilities for data translation and processing
+    utilities for data translation and processing.
     """
 
     homepage   = "http://www.gdal.org/"

var/spack/repos/builtin/packages/gdb/package.py

@@ -22,16 +22,15 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-
 from spack import *
 
 
 class Gdb(Package):
     """GDB, the GNU Project debugger, allows you to see what is going on
-       `inside' another program while it executes -- or what another
+    'inside' another program while it executes -- or what another
     program was doing at the moment it crashed.
-
     """
+
     homepage = "https://www.gnu.org/software/gdb"
     url = "http://ftp.gnu.org/gnu/gdb/gdb-7.10.tar.gz"
 

var/spack/repos/builtin/packages/gmsh/package.py

@@ -26,8 +26,7 @@
 
 
 class Gmsh(Package):
-    """
+    """Gmsh is a free 3D finite element grid generator with a built-in CAD engine
-    Gmsh is a free 3D finite element grid generator with a built-in CAD engine
     and post-processor. Its design goal is to provide a fast, light and
     user-friendly meshing tool with parametric input and advanced visualization
     capabilities. Gmsh is built around four modules: geometry, mesh, solver and
@@ -35,6 +34,7 @@ class Gmsh(Package):
     either interactively using the graphical user interface or in ASCII text
     files using Gmsh's own scripting language.
     """
+
     homepage = 'http://gmsh.info'
     url = 'http://gmsh.info/src/gmsh-2.11.0-source.tgz'
 

var/spack/repos/builtin/packages/libsplash/package.py

@@ -26,10 +26,9 @@
 
 
 class Libsplash(Package):
-    """
+    """libSplash aims at developing a HDF5-based I/O library for HPC
-    libSplash aims at developing a HDF5-based I/O library for HPC simulations.
+    simulations. It is created as an easy-to-use frontend for the standard HDF5
-    It is created as an easy-to-use frontend for the standard HDF5 library
+    library with support for MPI processes in a cluster environment. While the
-    with support for MPI processes in a cluster environment. While the
     standard HDF5 library provides detailed low-level control, libSplash
     simplifies tasks commonly found in large-scale HPC simulations, such as
     iterative computations and MPI distributed processes.

var/spack/repos/builtin/packages/lmod/package.py

@@ -27,14 +27,14 @@
 
 
 class Lmod(Package):
-    """
+    """Lmod is a Lua based module system that easily handles the MODULEPATH
-    Lmod is a Lua based module system that easily handles the MODULEPATH
     Hierarchical problem. Environment Modules provide a convenient way to
     dynamically change the users' environment through modulefiles. This
     includes easily adding or removing directories to the PATH environment
     variable. Modulefiles for Library packages provide environment variables
     that specify where the library and header files can be found.
     """
+
     homepage = 'https://www.tacc.utexas.edu/research-development/tacc-projects/lmod'
     url = 'https://github.com/TACC/Lmod/archive/6.4.1.tar.gz'
 

var/spack/repos/builtin/packages/lua-luafilesystem/package.py

@@ -26,8 +26,7 @@
 
 
 class LuaLuafilesystem(Package):
-    """
+    """LuaFileSystem is a Lua library developed to complement the set of
-    LuaFileSystem is a Lua library developed to complement the set of
     functions related to file systems offered by the standard Lua distribution.
 
     LuaFileSystem offers a portable way to access the underlying directory
@@ -35,6 +34,7 @@ class LuaLuafilesystem(Package):
 
     LuaFileSystem is free software and uses the same license as Lua 5.1
     """
+
     homepage = 'http://keplerproject.github.io/luafilesystem'
     url = 'https://github.com/keplerproject/luafilesystem/archive/v_1_6_3.tar.gz'
 

var/spack/repos/builtin/packages/mxml/package.py

@@ -26,10 +26,9 @@
 
 
 class Mxml(Package):
-    """
+    """Mini-XML is a small XML library that you can use to read and write XML
-    Mini-XML is a small XML library that you can use to read and write XML
     and XML-like data files in your application without requiring large
-    non-standard libraries
+    non-standard libraries.
     """
 
     homepage = "http://www.msweet.org"

var/spack/repos/builtin/packages/ncdu/package.py

@@ -26,8 +26,7 @@
 
 
 class Ncdu(Package):
-    """
+    """Ncdu is a disk usage analyzer with an ncurses interface. It is designed
-    Ncdu is a disk usage analyzer with an ncurses interface. It is designed
     to find space hogs on a remote server where you don't have an entire
     gaphical setup available, but it is a useful tool even on regular desktop
     systems. Ncdu aims to be fast, simple and easy to use, and should be able

var/spack/repos/builtin/packages/opari2/package.py

@@ -22,13 +22,11 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-
 from spack import *
 
 
 class Opari2(Package):
-    """
+    """OPARI2 is a source-to-source instrumentation tool for OpenMP and hybrid
-    OPARI2 is a source-to-source instrumentation tool for OpenMP and hybrid
     codes. It surrounds OpenMP directives and runtime library calls with calls
     to the POMP2 measurement interface. OPARI2 will provide you with a new
     initialization method that allows for multi-directory and parallel builds

var/spack/repos/builtin/packages/opencoarrays/package.py

@@ -26,8 +26,7 @@
 
 
 class Opencoarrays(CMakePackage):
-    """
+    """OpenCoarrays is an open-source software project that produces an
-    OpenCoarrays is an open-source software project that produces an
     application binary interface (ABI) supporting coarray Fortran (CAF)
     compilers, an application programming interface (API) that supports users
     of non-CAF compilers, and an associated compiler wrapper and program

var/spack/repos/builtin/packages/openjpeg/package.py

@@ -26,14 +26,14 @@
 
 
 class Openjpeg(Package):
-    """
+    """OpenJPEG is an open-source JPEG 2000 codec written in C language.
-    OpenJPEG is an open-source JPEG 2000 codec written in C language.
     It has been developed in order to promote the use of JPEG 2000, a
     still-image compression standard from the Joint Photographic
     Experts Group (JPEG).
     Since April 2015, it is officially recognized by ISO/IEC and
     ITU-T as a JPEG 2000 Reference Software.
     """
+
     homepage = "https://github.com/uclouvain/openjpeg"
     url      = "https://github.com/uclouvain/openjpeg/archive/version.2.1.tar.gz"
 

var/spack/repos/builtin/packages/parallel/package.py

@@ -26,8 +26,7 @@
 
 
 class Parallel(Package):
-    """
+    """GNU parallel is a shell tool for executing jobs in parallel using
-    GNU parallel is a shell tool for executing jobs in parallel using
     one or more computers. A job can be a single command or a small
     script that has to be run for each of the lines in the input.
     """

var/spack/repos/builtin/packages/petsc/package.py

@@ -27,8 +27,7 @@
 
 
 class Petsc(Package):
-    """
+    """PETSc is a suite of data structures and routines for the scalable
-    PETSc is a suite of data structures and routines for the scalable
     (parallel) solution of scientific applications modeled by partial
     differential equations.
     """

var/spack/repos/builtin/packages/pngwriter/package.py

@@ -26,14 +26,13 @@
 
 
 class Pngwriter(Package):
-    """
+    """PNGwriter is a very easy to use open source graphics library that uses
-    PNGwriter is a very easy to use open source graphics library that uses PNG
+    PNG as its output format. The interface has been designed to be as simple
-    as its output format. The interface has been designed to be as simple and
+    and intuitive as possible. It supports plotting and reading pixels in the
-    intuitive as possible. It supports plotting and reading pixels in the RGB
+    RGB (red, green, blue), HSV (hue, saturation, value/brightness) and CMYK
-    (red, green, blue), HSV (hue, saturation, value/brightness) and CMYK (cyan,
+    (cyan, magenta, yellow, black) colour spaces, basic shapes, scaling,
-    magenta, yellow, black) colour spaces, basic shapes, scaling, bilinear
+    bilinear interpolation, full TrueType antialiased and rotated text support,
-    interpolation, full TrueType antialiased and rotated text support, bezier
+    bezier curves, opening existing PNG images and more.
-    curves, opening existing PNG images and more.
     """
 
     homepage = "http://pngwriter.sourceforge.net/"

var/spack/repos/builtin/packages/py-coverage/package.py

@@ -27,7 +27,7 @@
 
 class PyCoverage(Package):
     """ Testing coverage checker for python """
-    # FIXME: add a proper url for your package's homepage here.
+
     homepage = "http://nedbatchelder.com/code/coverage/"
     url      = "https://pypi.python.org/packages/source/c/coverage/coverage-4.0a6.tar.gz"
 

var/spack/repos/builtin/packages/py-prettytable/package.py

@@ -22,16 +22,15 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-from spack import depends_on, extends, version
+from spack import *
-from spack import Package
 
 
 class PyPrettytable(Package):
-    """
+    """PrettyTable is a simple Python library designed to make
-    PrettyTable is a simple Python library designed to make
     it quick and easy to represent tabular data in visually
-    appealing ASCII tables
+    appealing ASCII tables.
     """
+
     homepage = "https://code.google.com/archive/p/prettytable/"
     url      = "https://pypi.python.org/packages/e0/a1/36203205f77ccf98f3c6cf17cf068c972e6458d7e58509ca66da949ca347/prettytable-0.7.2.tar.gz"
 

var/spack/repos/builtin/packages/py-tuiview/package.py

@@ -26,10 +26,10 @@
 
 
 class PyTuiview(Package):
-    """
+    """TuiView is a lightweight raster GIS with powerful raster attribute
-       TuiView is a lightweight raster GIS with powerful raster attribute
     table manipulation abilities.
     """
+
     homepage = "https://bitbucket.org/chchrsc/tuiview"
     url      = "https://bitbucket.org/chchrsc/tuiview/get/tuiview-1.1.7.tar.gz"
 

var/spack/repos/builtin/packages/scorep/package.py

@@ -22,15 +22,13 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-
 from spack import *
 
 
 class Scorep(Package):
-    """
+    """The Score-P measurement infrastructure is a highly scalable and
-    The Score-P measurement infrastructure is a highly scalable and easy-to-use
+    easy-to-use tool suite for profiling, event tracing, and online analysis
-    tool suite for profiling, event tracing, and online analysis of HPC
+    of HPC applications.
-    applications.
     """
 
     homepage = "http://www.vi-hps.org/projects/score-p"

var/spack/repos/builtin/packages/screen/package.py

@@ -26,8 +26,7 @@
 
 
 class Screen(Package):
-    """
+    """Screen is a full-screen window manager that multiplexes a physical
-    Screen is a full-screen window manager that multiplexes a physical
     terminal between several processes, typically interactive shells.
     """
 

var/spack/repos/builtin/packages/swiftsim/package.py

@@ -22,15 +22,12 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-
 from spack import *
-
 import llnl.util.tty as tty
 
 
 class Swiftsim(Package):
-    """
+    """SPH With Inter-dependent Fine-grained Tasking (SWIFT) provides
-    SPH With Inter-dependent Fine-grained Tasking (SWIFT) provides
     astrophysicists with a state of the art framework to perform
     particle based simulations.
     """

var/spack/repos/builtin/packages/tau/package.py

@@ -22,21 +22,18 @@
 # License along with this program; if not, write to the Free Software
 # Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
 ##############################################################################
-
 from spack import *
-
 import os
 import os.path
-
 from llnl.util.filesystem import join_path
 
 
 class Tau(Package):
-    """
+    """A portable profiling and tracing toolkit for performance
-    A portable profiling and tracing toolkit for performance
     analysis of parallel programs written in Fortran, C, C++, UPC,
     Java, Python.
     """
+
     homepage = "http://www.cs.uoregon.edu/research/tau"
     url      = "https://www.cs.uoregon.edu/research/tau/tau_releases/tau-2.25.tar.gz"
 

var/spack/repos/builtin/packages/xerces-c/package.py

@@ -26,9 +26,9 @@
 
 
 class XercesC(Package):
-    """ Xerces-C++ is a validating XML parser written in a portable subset of C++.
+    """Xerces-C++ is a validating XML parser written in a portable subset of
-    Xerces-C++ makes it easy to give your application the ability to read and
+    C++. Xerces-C++ makes it easy to give your application the ability to read
-    write XML data. A shared library is provided for parsing, generating,
+    and write XML data. A shared library is provided for parsing, generating,
     manipulating, and validating XML documents using the DOM, SAX, and SAX2
     APIs.
     """

var/spack/repos/builtin/packages/zsh/package.py

@@ -26,11 +26,11 @@
 
 
 class Zsh(Package):
+    """Zsh is a shell designed for interactive use, although it is also a
+    powerful scripting language. Many of the useful features of bash, ksh, and
+    tcsh were incorporated into zsh; many original features were added.
     """
-    Zsh is a shell designed for interactive use, although it is also a powerful
+
-    scripting language. Many of the useful features of bash, ksh, and tcsh were
-    incorporated into zsh; many original features were added.
-    """
     homepage = "http://www.zsh.org"
     url = "http://downloads.sourceforge.net/project/zsh/zsh/5.1.1/zsh-5.1.1.tar.gz"