Start of basic documentation

lib/spack/docs/.gitignore

@@ -0,0 +1,2 @@
+spack*.rst
+_build

lib/spack/docs/Makefile

@@ -7,6 +7,9 @@ SPHINXBUILD   = sphinx-build
 PAPER         =
 BUILDDIR      = _build
 
+export PYTHONPATH = ../../spack
+APIDOC_FILES  = spack*.rst
+
 # Internal variables.
 PAPEROPT_a4     = -D latex_paper_size=a4
 PAPEROPT_letter = -D latex_paper_size=letter
@@ -14,10 +17,13 @@ ALLSPHINXOPTS   = -d $(BUILDDIR)/doctrees $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 # the i18n builder cannot share the environment and doctrees with the others
 I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
-.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext
+.PHONY: help clean html dirhtml singlehtml pickle json htmlhelp qthelp devhelp epub latex latexpdf text man changes linkcheck doctest gettext apidoc
 
 all: html
 
+apidoc:
+	sphinx-apidoc -T -o . $(PYTHONPATH)/spack
+
 help:
 	@echo "Please use \`make <target>' where <target> is one of"
 	@echo "  html       to make standalone HTML files"
@@ -41,9 +47,9 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
-	-rm -rf $(BUILDDIR)/*
+	-rm -rf $(BUILDDIR)/* $(APIDOC_FILES)
 
-html:
+html: apidoc
 	$(SPHINXBUILD) -b html $(ALLSPHINXOPTS) $(BUILDDIR)/html
 	@echo
 	@echo "Build finished. The HTML pages are in $(BUILDDIR)/html."

lib/spack/docs/_themes/sphinx_rtd_theme/footer.html

@@ -24,7 +24,7 @@
   {%- if last_updated %}
     {% trans last_updated=last_updated|e %}Last updated on {{ last_updated }}.{% endtrans %}
   {%- endif %}
-  </p>
-
+  &nbsp;&nbsp;
   {% trans %}<a href="https://www.github.com/snide/sphinx_rtd_theme">Sphinx theme</a> provided by <a href="http://readthedocs.org">Read the Docs</a>{% endtrans %}
+  </p>
 </footer>

lib/spack/docs/basic_usage.rst

@@ -0,0 +1,233 @@
+Basic usage
+=====================
+
+Nearly everything you do wtih spack will involve the ``spack``
+command.  Like many well-known tools (``git``, ``cvs``, ``svn``,
+``yum``, ``port``, ``apt-get``, etc.), ``spack`` is generally called
+with a *subcommand* indicating the action you want to perform.
+
+Getting Help
+-----------------------
+
+
+``spack help``
+~~~~~~~~~~~~~~~~~~~~~~
+
+The first subcommand you should know is ``spack help``.  Run with no
+arguments, it will give a list of all spack options and subcommands:
+
+.. command-output:: spack help
+
+If you want help on the usage of a particular subcommand, you can pass
+it as an argument to ``spack help``:
+
+.. command-output:: spack help install
+
+Alternately, you can use ``spack -h`` in place of ``spack help``, or
+``spack <subcommand> -h`` to get help on a particular subcommand.
+
+
+Viewing available packages
+------------------------------
+
+The first thing you will likely want to do with spack is find out what
+software is available to install.  There are two main commands for
+this: ``spack list`` and ``spack info``.
+
+
+``spack list``
+~~~~~~~~~~~~~~~~
+
+The ``spack list`` command does what you might expect. it prints out a
+list of all the available packages you can install.  Use it like
+this:
+
+.. command-output:: spack list
+
+The packages are listed by name in alphabetical order.  If you just
+want to see *installed* packages, you should use ``spack list -i``
+
+
+``spack info``
+~~~~~~~~~~~~~~~~
+
+To get information on a particular package from the full list, you can
+run ``spack info <package name>``.  e.g., for ``mpich``:
+
+.. command-output:: spack info mpich
+
+This gives basic information about the package, such as where it can
+be downloaded, what other packages it depends on, virtual package
+information, and a text description, if one is available.  We'll give
+more details on dependencies and virtual dependencies later in this
+guide.
+
+
+Installing and uninstalling
+------------------------------
+
+``spack install``
+~~~~~~~~~~~~~~~~~~~~~
+
+You can install any package from ``spack list``, using ``spack
+install``.  In the simplest case, if you just want the latest version
+and you don't care about any configuration, you can just run ``spack
+install <package>``:
+
+.. code-block:: sh
+
+   spack install mpileaks
+
+This will fetch the tarball for ``mpileaks``, expand it, verify that
+it was donwloaded without errors, build the package, and install it in
+its own directory in ``$SPACK_HOME/opt``.  If the requested packages
+depends on other packages in order to build, then they will also be
+fetched and installed.
+
+Spack also allows you to ask for *specific* configurations of a
+package.  For example, if you want to install something with a
+specific version, you can add ``@`` after the package name, followed
+by the version you want:
+
+.. code-block:: sh
+
+   spack install mpich@3.0.4
+
+You can install as many versions of the same pacakge as you want, and
+they will not interfere with each other.  Spack installs each package
+into its own unique prefix.  If you or another user links a library
+against soething you install using Spack, it will continue to work
+until you explicitly uninstall it.
+
+The version isn't all that you can customize on a spack command line.
+Spack can install many configurations, with different versions,
+compilers, compiler versions, compile-time options (variants), and
+even architectures (e.g., on a machine that requires cross-compiling).
+Spack is also unique in that it lets you customize the *dependencies*
+you build a package with.  That is, you could have two configurations
+of the same version of a package: one built with boost 1.39.0, and the
+other version built with version 1.43.0.
+
+Spack calls the descriptor used to refer to a particular package
+configuration a **spec**.  In the command lines above, both
+``mpileaks`` and ``mpileaks@3.0.4`` are specs.  Specs and their syntax
+are covered in more detail in :ref:`sec-specs`.
+
+
+
+
+``spack uninstall``
+~~~~~~~~~~~~~~~~~~~~~
+
+To uninstall a package, just type ``spack uninstall <package>``.  This
+will completely remove the directory in which the package was installed.
+
+.. code-block:: sh
+
+   spack uninstall mpich
+
+If there are other installed packages depend on the package you're
+uninstalling, spack will issue a warning to this effect.  In general,
+you should remove the other packages *before* removing the package
+they depend on, or you risk breaking packages on your system.  If you
+still want to remove the package without regard for its dependencies,
+you can run ``spack uninstall -f <package>`` to override Spack's
+warning.
+
+If you have more than one version of the same package installed, spack
+may not be able to figure out which on eyou want uninstalled.  For
+example, if you have both ``mpich@3.0.2`` and ``mpich@3.1`` installed,
+and you type ``spack uninstall mpich``, then Spack will not know which
+one you're referring to, and it will ask you to be more specific by
+providing a version to differentiate, For example, ``spack uninstall
+mpich@3.1`` is unambiguous.
+
+
+.. _sec-specs:
+
+Specs
+-------------------------
+
+Dependencies
+-------------------------
+
+Virtual dependencies
+-------------------------
+
+Versions, compilers, and architectures
+----------------------------------------
+
+``spack versions``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+``spack compilers``
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Architectures
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Spack's specs allow insatllations for multiple architectures to coexist
+within the same prefix.  It is also intended to support multiple
+architecutres for cross-compilation.
+
+
+Package lifecycle
+------------------------------
+
+The ``spack install`` command performs a number of tasks before it
+finally installs each package.  It downloads an archive, expands it in
+a temporary directory, and only then performs the installation.  Spack
+has several commands that allow finer-grained control over each of
+these stages of the build process.
+
+
+``spack fetch``
+~~~~~~~~~~~~~~~~~
+
+This is the first step of ``spack install``.  It takes a spec and
+determines the correct download URL to use for the requested package
+version.  It then downloads the archive, checks it against an MD5
+checksum, and stores it in a staging directory if the check was
+successful.  The staging directory will be located under
+``$SPACK_HOME/var/spack``.
+
+If run after the archive has already been downloaded, ``spack fetch``
+is idempotent and will not download the archive again.
+
+``spack stage``
+~~~~~~~~~~~~~~~~~
+
+This is the second step in installation after ``spack fetch``.  It
+expands the downloaded archive in its temporary directory, where it
+will be built by ``spack install``.  If the archive has already been
+expanded, then this command does nothing.
+
+``spack clean``
+~~~~~~~~~~~~~~~~~
+
+This command has several variations, each undoing one of the
+installation tasks.  They are:
+
+``spack clean``
+  Runs ``make clean`` in the expanded archive directory.  This is useful
+  if an attempted  build failed, and something needs to be changed to get
+  a package to build.  If a particular package does not have a ``make clean``
+  target, this will do nothing.
+
+``spack clean -w`` or ``spack clean --work``
+  This deletes the entire build directory and re-expands it from the downloaded
+  archive. This is useful if a package does not support a proper ``make clean``
+  target.
+
+``spack clean -d`` or ``spack clean --dist``
+  This deletes the build directory *and* the downloaded archive.  If
+  ``fetch``, ``stage``, or ``install`` are run again after this, the
+  process will start from scratch, and the archive archive will be
+  downloaded again.  Useful if somehow a bad archive is downloaded
+  accidentally and needs to be cleaned out of the staging area.
+
+
+
+
+``spack purge``
+~~~~~~~~~~~~~~~~~

lib/spack/docs/conf.py

@@ -16,7 +16,10 @@
 # If extensions (or modules to document with autodoc) are in another directory,
 # add these directories to sys.path here. If the directory is relative to the
 # documentation root, use os.path.abspath to make it absolute, like shown here.
-#sys.path.insert(0, os.path.abspath('.'))
+sys.path.insert(0, os.path.abspath('exts'))
+os.environ['PATH'] += os.pathsep + '../../../bin'
+
+todo_include_todos = True
 
 # -- General configuration -----------------------------------------------------
 
@@ -25,7 +28,10 @@
 
 # Add any Sphinx extension module names here, as strings. They can be extensions
 # coming with Sphinx (named 'sphinx.ext.*') or your custom ones.
-extensions = ['sphinx.ext.autodoc']
+extensions = ['sphinx.ext.autodoc',
+              'sphinx.ext.graphviz',
+              'sphinx.ext.todo',
+              'sphinxcontrib.programoutput']
 
 # Add any paths that contain templates here, relative to this directory.
 templates_path = ['_templates']

lib/spack/docs/developer_guide.rst

@@ -0,0 +1,31 @@
+Developer Guide
+=====================
+
+
+Spec objects
+-------------------------
+
+Package objects
+-------------------------
+
+Stage objects
+-------------------------
+
+Writing commands
+-------------------------
+
+Unit tests
+-------------------------
+
+Unit testing
+-------------------------
+
+
+Developer commands
+-------------------------
+
+``spack doc``
+~~~~~~~~~~~~~~~~~
+
+``spack test``
+~~~~~~~~~~~~~~~~~

lib/spack/docs/exts/sphinxcontrib/LICENSE

@@ -0,0 +1,25 @@
+Copyright (c) 2010, 2011, 2012 Sebastian Wiesner <lunaryorn@googlemail.com>
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without
+modification, are permitted provided that the following conditions are
+met:
+
+* Redistributions of source code must retain the above copyright
+  notice, this list of conditions and the following disclaimer.
+
+* Redistributions in binary form must reproduce the above copyright
+  notice, this list of conditions and the following disclaimer in the
+  documentation and/or other materials provided with the distribution.
+
+THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+"AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR
+A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT
+OWNER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE,
+DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
+(INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
+OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

lib/spack/docs/exts/sphinxcontrib/__init__.py

@@ -0,0 +1,9 @@
+# -*- coding: utf-8 -*-
+"""
+    sphinxcontrib
+    ~~~~~~~~~~~~~
+
+    Contains 3rd party Sphinx extensions.
+"""
+
+__import__('pkg_resources').declare_namespace(__name__)

lib/spack/docs/exts/sphinxcontrib/programoutput.py

@@ -0,0 +1,263 @@
+# -*- coding: utf-8 -*-
+# Copyright (c) 2010, 2011, 2012, Sebastian Wiesner <lunaryorn@gmail.com>
+# All rights reserved.
+
+# Redistribution and use in source and binary forms, with or without
+# modification, are permitted provided that the following conditions are met:
+
+# 1. Redistributions of source code must retain the above copyright notice,
+#    this list of conditions and the following disclaimer.
+# 2. Redistributions in binary form must reproduce the above copyright
+#    notice, this list of conditions and the following disclaimer in the
+#    documentation and/or other materials provided with the distribution.
+
+# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
+# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
+# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
+# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
+# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
+# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
+# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
+# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
+# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
+# POSSIBILITY OF SUCH DAMAGE.
+
+"""
+    sphinxcontrib.programoutput
+    ===========================
+
+    This extension provides a directive to include the output of commands as
+    literal block while building the docs.
+
+    .. moduleauthor::  Sebastian Wiesner  <lunaryorn@gmail.com>
+"""
+
+from __future__ import (print_function, division, unicode_literals,
+                        absolute_import)
+
+import sys
+import os
+import shlex
+from subprocess import Popen, PIPE, STDOUT
+from collections import defaultdict, namedtuple
+
+from docutils import nodes
+from docutils.parsers import rst
+from docutils.parsers.rst.directives import flag, unchanged, nonnegative_int
+
+
+__version__ = '0.9'
+
+
+class program_output(nodes.Element):
+    pass
+
+
+def _slice(value):
+    parts = [int(v.strip()) for v in value.split(',')]
+    if len(parts) > 2:
+        raise ValueError('too many slice parts')
+    return tuple((parts + [None] * 2)[:2])
+
+
+class ProgramOutputDirective(rst.Directive):
+    has_content = False
+    final_argument_whitespace = True
+    required_arguments = 1
+
+    option_spec = dict(shell=flag, prompt=flag, nostderr=flag,
+                       ellipsis=_slice, extraargs=unchanged,
+                       returncode=nonnegative_int, cwd=unchanged)
+
+    def run(self):
+        env = self.state.document.settings.env
+
+        node = program_output()
+        node.line = self.lineno
+        node['command'] = self.arguments[0]
+
+        if self.name == 'command-output':
+            node['show_prompt'] = True
+        else:
+            node['show_prompt'] = 'prompt' in self.options
+
+        node['hide_standard_error'] = 'nostderr' in self.options
+        node['extraargs'] = self.options.get('extraargs', '')
+        _, cwd = env.relfn2path(self.options.get('cwd', '/'))
+        node['working_directory'] = cwd
+        node['use_shell'] = 'shell' in self.options
+        node['returncode'] = self.options.get('returncode', 0)
+        if 'ellipsis' in self.options:
+            node['strip_lines'] = self.options['ellipsis']
+        return [node]
+
+
+_Command = namedtuple(
+    'Command', 'command shell hide_standard_error working_directory')
+
+
+class Command(_Command):
+    """
+    A command to be executed.
+    """
+
+    def __new__(cls, command, shell=False, hide_standard_error=False,
+                working_directory='/'):
+        if isinstance(command, list):
+            command = tuple(command)
+        # `chdir()` resolves symlinks, so we need to resolve them too for
+        # caching to make sure that different symlinks to the same directory
+        # don't result in different cache keys.  Also normalize paths to make
+        # sure that identical paths are also equal as strings.
+        working_directory = os.path.normpath(os.path.realpath(
+            working_directory))
+        return _Command.__new__(cls, command, shell, hide_standard_error,
+                                working_directory)
+
+    @classmethod
+    def from_program_output_node(cls, node):
+        """
+        Create a command from a :class:`program_output` node.
+        """
+        extraargs = node.get('extraargs', '')
+        command = (node['command'] + ' ' + extraargs).strip()
+        return cls(command, node['use_shell'],
+                   node['hide_standard_error'], node['working_directory'])
+
+    def execute(self):
+        """
+        Execute this command.
+
+        Return the :class:`~subprocess.Popen` object representing the running
+        command.
+        """
+        if self.shell:
+            if sys.version_info[0] < 3 and isinstance(self.command, unicode):
+                command = self.command.encode(sys.getfilesystemencoding())
+            else:
+                command = self.command
+        else:
+            if sys.version_info[0] < 3 and isinstance(self.command, unicode):
+                command = shlex.split(self.command.encode(
+                    sys.getfilesystemencoding()))
+            elif isinstance(self.command, str):
+                command = shlex.split(self.command)
+            else:
+                command = self.command
+        return Popen(command, shell=self.shell, stdout=PIPE,
+                     stderr=PIPE if self.hide_standard_error else STDOUT,
+                     cwd=self.working_directory)
+
+    def get_output(self):
+        """
+        Get the output of this command.
+
+        Return a tuple ``(returncode, output)``.  ``returncode`` is the
+        integral return code of the process, ``output`` is the output as
+        unicode string, with final trailing spaces and new lines stripped.
+        """
+        process = self.execute()
+        output = process.communicate()[0].decode(
+            sys.getfilesystemencoding(), 'replace').rstrip()
+        return process.returncode, output
+
+    def __str__(self):
+        if isinstance(self.command, tuple):
+            return repr(list(self.command))
+        return repr(self.command)
+
+
+class ProgramOutputCache(defaultdict):
+    """
+    Execute command and cache their output.
+
+    This class is a mapping.  Its keys are :class:`Command` objects represeting
+    command invocations.  Its values are tuples of the form ``(returncode,
+    output)``, where ``returncode`` is the integral return code of the command,
+    and ``output`` is the output as unicode string.
+
+    The first time, a key is retrieved from this object, the command is
+    invoked, and its result is cached.  Subsequent access to the same key
+    returns the cached value.
+    """
+
+    def __missing__(self, command):
+        """
+        Called, if a command was not found in the cache.
+
+        ``command`` is an instance of :class:`Command`.
+        """
+        result = command.get_output()
+        self[command] = result
+        return result
+
+
+def run_programs(app, doctree):
+    """
+    Execute all programs represented by ``program_output`` nodes in
+    ``doctree``.  Each ``program_output`` node in ``doctree`` is then
+    replaced with a node, that represents the output of this program.
+
+    The program output is retrieved from the cache in
+    ``app.env.programoutput_cache``.
+    """
+    if app.config.programoutput_use_ansi:
+        # enable ANSI support, if requested by config
+        from sphinxcontrib.ansi import ansi_literal_block
+        node_class = ansi_literal_block
+    else:
+        node_class = nodes.literal_block
+
+    cache = app.env.programoutput_cache
+
+    for node in doctree.traverse(program_output):
+        command = Command.from_program_output_node(node)
+        try:
+            returncode, output = cache[command]
+        except EnvironmentError as error:
+            error_message = 'Command {0} failed: {1}'.format(command, error)
+            error_node = doctree.reporter.error(error_message, base_node=node)
+            node.replace_self(error_node)
+        else:
+            if returncode != node['returncode']:
+                app.warn('Unexpected return code {0} from command {1}'.format(
+                    returncode, command))
+
+            # replace lines with ..., if ellipsis is specified
+            if 'strip_lines' in node:
+                lines = output.splitlines()
+                start, stop = node['strip_lines']
+                lines[start:stop] = ['...']
+                output = '\n'.join(lines)
+
+            if node['show_prompt']:
+                tmpl = app.config.programoutput_prompt_template
+                output = tmpl.format(command=node['command'], output=output,
+                                     returncode=returncode)
+
+            new_node = node_class(output, output)
+            new_node['language'] = 'text'
+            node.replace_self(new_node)
+
+
+def init_cache(app):
+    """
+    Initialize the cache for program output at
+    ``app.env.programoutput_cache``, if not already present (e.g. being
+    loaded from a pickled environment).
+
+    The cache is of type :class:`ProgramOutputCache`.
+    """
+    if not hasattr(app.env, 'programoutput_cache'):
+        app.env.programoutput_cache = ProgramOutputCache()
+
+
+def setup(app):
+    app.add_config_value('programoutput_use_ansi', False, 'env')
+    app.add_config_value('programoutput_prompt_template',
+                         '$ {command}\n{output}', 'env')
+    app.add_directive('program-output', ProgramOutputDirective)
+    app.add_directive('command-output', ProgramOutputDirective)
+    app.connect(str('builder-inited'), init_cache)
+    app.connect(str('doctree-read'), run_programs)

lib/spack/docs/features.rst

@@ -0,0 +1,96 @@
+Feature Overview
+==================
+
+This is an 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 packages is easy with Spack when you just want the default
+version.  This installs the latest version of mpileaks and all of its
+dependencies:
+
+.. code-block:: sh
+
+   $ spack install mpileaks
+
+Custom versions & configurations
+-------------------------------------------
+
+If there's some aspect of your package that you want to customize, you
+can do that too.
+
+.. code-block:: sh
+
+   # Install a particular version by appending @
+   $ spack install mpileaks@1.1.2
+
+   # Or your favorite compiler (and its version), with %
+   $ spack install mpileaks@1.1.2 %gcc@4.7.3
+
+   # Add some special compile-time options with +
+   $ spack install mpileaks@1.1.2 %gcc@4.7.3 +debug
+
+   # Cross-compile for a different architecture with =
+   $ spack install mpileaks@1.1.2 =bgqos_0
+
+Customize dependencies
+-------------------------------------
+
+You can customize package dependencies with ``^``.  Suppose that
+``mpileaks`` depends indirectly on ``libelf`` and ``libdwarf``.  Using
+``^``, you can add custom configurations for the dependencies, too.
+
+.. code-block:: sh
+
+   # 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 configuration in its own prefix,
+so you can install as many different versions and configurations as
+you want.  New installs will not break existing ones.
+
+
+Packages can peacefully coexist
+-------------------------------------
+
+Spack uses ``RPATH`` everywhere, so users do not need to customize
+``LD_LIBRARY_PATH``.  If you use a library or run a program, it will
+run the way you built it.
+
+
+Creating packages is easy
+-------------------------------------
+
+To create your own packages, give spack the tarball URL.  Spack
+creates all the boilerplate for you.
+
+.. code-block:: sh
+
+   $ spack create http://scalability.llnl.gov/mpileaks/downloads/mpileaks-1.0.tar.gz
+
+Creates ``mpileaks.py``:
+
+.. code-block:: python
+
+   from spack import *
+
+   class Mpileaks(Package):
+       homepage = "http://www.example.com/"
+       url      = "http://scalability.llnl.gov/mpileaks/downloads/mpileaks-1.0.tar.gz"
+       md5      = "4136d7b4c04df68b686570afa26988ac"
+
+       def install(self, prefix):
+           configure("--prefix=%s" % prefix)
+           make()
+           make("install")
+
+Packages are pure python, so you have complete freedom when writing
+build code.  Spack also provides a number of feature that make it
+easier to write packages.

lib/spack/docs/getting_started.rst

@@ -0,0 +1,44 @@
+Getting Started
+====================
+
+Download
+--------------------
+
+Getting spack is easy.  Clone it using `git <http://git-scm.com->`_
+with the following command:
+
+.. code-block:: sh
+
+   $ git clone ssh://git@cz-stash.llnl.gov:7999/scale/spack.git
+
+This will create a directory called ``spack``.  We'll assume that the
+full path to this directory is in some environment called
+``SPACK_HOME``.  Add ``$SPACK_HOME/bin`` to your path and you're ready
+to go:
+
+.. code-block:: sh
+
+   $ export PATH=spack/bin:$SPACK_HOME
+   $ spack install mpich
+
+In general, most of your interactions with Spack will be through the
+``spack`` command.
+
+
+Install
+--------------------
+
+You don't need to install Spack; it's ready to run as soon as you
+clone it from git.
+
+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
+
+    $ spack bootstrap /my/favorite/prefix
+
+This will install a new spack script in /my/favorite/prefix/bin, which
+you can use just like you would the regular spack script.  Each copy
+of spack installs packages into its own ``$PREFIX/opt`` directory.

lib/spack/docs/index.rst

@@ -3,15 +3,39 @@
    You can adapt this file completely to your liking, but it should at least
    contain the root `toctree` directive.
 
-Welcome to Spack's documentation!
+Spack Documentation
 =================================
 
-Contents:
+Spack builds and installs software the way you want it.  Other tools
+let you install the latest version once.  Spack lets you install the
+versions you want, built with the compilers, libraries, and options
+you want.  Spack is non-destructive; installing a new version does not
+break your old installs.  See the :doc:`features` for more highlights.
+
+Get spack and install your first package:
+
+.. code-block:: sh
+
+   $ git clone ssh://git@cz-stash.llnl.gov:7999/scale/spack.git
+   $ cd spack/bin
+   $ ./spack install mpich
+
+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
 
-
+   features
+   getting_started
+   basic_usage
+   packaging_guide
+   site_configuration
+   developer_guide
+   API Docs <spack>
 
 Indices and tables
 ==================
@@ -19,4 +43,3 @@ Indices and tables
 * :ref:`genindex`
 * :ref:`modindex`
 * :ref:`search`
-

lib/spack/docs/packaging_guide.rst

@@ -0,0 +1,35 @@
+Packaging Guide
+=====================
+
+
+Package files
+-------------------------
+
+
+Dependencies
+-------------------------
+
+
+Virtual dependencies
+-------------------------
+
+
+Virtual dependencies
+-------------------------
+
+
+
+Packaging commands
+-------------------------
+
+``spack edit``
+~~~~~~~~~~~~~~~~~~~~
+
+``spack create``
+~~~~~~~~~~~~~~~~~~~~
+
+``spack checksum``
+~~~~~~~~~~~~~~~~~~~~
+
+``spack graph``
+~~~~~~~~~~~~~~~~~~~~

lib/spack/docs/site_configuration.rst

@@ -0,0 +1,9 @@
+Site-specific configuration
+===================================
+
+Temporary space
+----------------------------
+
+
+Concretization policies
+----------------------------