Update documentation to add an auto-generated list of packages.

lib/spack/docs/.gitignore

@@ -1,2 +1,3 @@
+package_list.rst
 spack*.rst
 _build

lib/spack/docs/Makefile

@@ -21,6 +21,12 @@ I18NSPHINXOPTS  = $(PAPEROPT_$(PAPER)) $(SPHINXOPTS) .
 
 all: html
 
+#
+# This autogenerates a package list.
+#
+package_list:
+	spack info -r > package_list.rst
+
 #
 # This creates a git repository and commits generated html docs.
 # It them pushes the new branch into THIS repository as gh-pages.
@@ -69,9 +75,10 @@ help:
 	@echo "  doctest    to run all doctests embedded in the documentation (if enabled)"
 
 clean:
+	-rm -f package_list.rst
 	-rm -rf $(BUILDDIR)/* $(APIDOC_FILES)
 
-html: apidoc
+html: apidoc package_list
 	$(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

@@ -13,7 +13,7 @@
   <hr/>
 
   <p>
-    &copy; Copyright 2013,
+    &copy; Copyright 2013-2014,
     <a href="https://scalability.llnl.gov/">Lawrence Livermore National Laboratory</a>.
     <br/>
     Written by Todd Gamblin, <a href="mailto:tgamblin@llnl.gov">tgamblin@llnl.gov</a>, LLNL-CODE-647188

lib/spack/docs/conf.py

@@ -90,7 +90,7 @@
 
 # General information about the project.
 project = u'Spack'
-copyright = u'2013, Lawrence Livermore National Laboratory'
+copyright = u'2013-2014, Lawrence Livermore National Laboratory'
 
 # The version info for the project you're documenting, acts as replacement for
 # |version| and |release|, also used in various other places throughout the

lib/spack/docs/index.rst

@@ -48,6 +48,7 @@ Table of Contents
    packaging_guide
    site_configuration
    developer_guide
+   package_list
    API Docs <spack>
 
 Indices and tables

lib/spack/llnl/util/tty/colify.py

@@ -109,13 +109,15 @@ def colify(elts, **options):
     # elts needs to be an array of strings so we can count the elements
     elts = [str(elt) for elt in elts]
     if not elts:
-        return
+        return (0, ())
 
     if not tty:
         if tty is False or not isatty(output):
             for elt in elts:
                 output.write("%s\n" % elt)
-            return
+
+            maxlen = max(len(str(s)) for s in elts)
+            return (1, (maxlen,))
 
     console_cols = options.get("cols", None)
     if not console_cols:
@@ -150,6 +152,8 @@ def colify(elts, **options):
         if row == rows_last_col:
             cols -= 1
 
+    return (config.cols, tuple(config.widths))
+
 
 def colified(elts, **options):
     """Invokes the colify() function but returns the result as a string

lib/spack/spack/cmd/info.py

@@ -24,52 +24,132 @@
 ##############################################################################
 import re
 import textwrap
-from llnl.util.tty.colify import colify
+from StringIO import StringIO
+from llnl.util.tty.colify import *
 import spack
 
 description = "Get detailed information on a particular package"
 
 def setup_parser(subparser):
-    subparser.add_argument('name', metavar="PACKAGE", help="name of packages to get info on")
+    subparser.add_argument('-r', '--rst', action='store_true',
+                           help="List all packages in reStructured text, for docs.")
+    subparser.add_argument('name', metavar="PACKAGE", nargs='?', help="name of packages to get info on")
 
 
-def info(parser, args):
-    package = spack.db.get(args.name)
-    print "Package:   ", package.name
-    print "Homepage:  ", package.homepage
+def format_doc(pkg, **kwargs):
+    """Wrap doc string at 72 characters and format nicely"""
+    indent = kwargs.get('indent', 0)
+
+    if not pkg.__doc__:
+        return ""
+
+    doc = re.sub(r'\s+', ' ', pkg.__doc__)
+    lines = textwrap.wrap(doc, 72)
+    results = StringIO()
+    for line in lines:
+        results.write((" " * indent) + line + "\n")
+    return results.getvalue()
+
+
+def github_url(pkg):
+    """Link to a package file on github."""
+    return ("https://github.com/scalability-llnl/spack/blob/master/var/spack/packages/%s/package.py" %
+            pkg.name)
+
+
+def rst_table(elts):
+    """Print out a RST-style table."""
+    cols = StringIO()
+    ncol, widths = colify(elts, output=cols, tty=True)
+    header = " ".join("=" * (w-1) for w in widths)
+    return "%s\n%s%s" % (header, cols.getvalue(), header)
+
+
+def info_rst():
+    """Print out information on all packages in restructured text."""
+    pkgs = sorted(spack.db.all_packages(), key=lambda s:s.name.lower())
+
+    print "Package List"
+    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.name for p in pkgs)
+    print
+    print "-----"
+
+    # Output some text for each package.
+    for pkg in pkgs:
+        print
+        print ".. _%s:" % pkg.name
+        print
+        print pkg.name
+        print "-" * len(pkg.name)
+        print "Links"
+        print "    * `Homepage <%s>`__" % pkg.homepage
+        print "    * `%s/package.py <%s>`__" % (pkg.name, github_url(pkg))
+        print
+        if pkg.dependencies:
+            print "Dependencies"
+            print "  " + ", ".join("`%s`_" % d if d != "mpi" else d
+                                   for d in pkg.dependencies)
+            print
+        print "Description"
+        print format_doc(pkg, indent=2)
+        print
+        print "-----"
+
+
+def info_text(pkg):
+    """Print out a plain text description of a package."""
+    print "Package:   ", pkg.name
+    print "Homepage:  ", pkg.homepage
 
     print
     print "Safe versions:  "
 
-    if not package.versions:
+    if not pkg.versions:
         print("None.")
     else:
-        maxlen = max(len(str(v)) for v in package.versions)
+        maxlen = max(len(str(v)) for v in pkg.versions)
         fmt = "%%-%ss" % maxlen
-        for v in reversed(sorted(package.versions)):
-            print "    " + (fmt % v) + "    " + package.url_for_version(v)
+        for v in reversed(sorted(pkg.versions)):
+            print "    " + (fmt % v) + "    " + pkg.url_for_version(v)
 
     print
     print "Dependencies:"
-    if package.dependencies:
-        colify(package.dependencies, indent=4)
+    if pkg.dependencies:
+        colify(pkg.dependencies, indent=4)
     else:
         print "    None"
 
     print
     print "Virtual packages: "
-    if package.provided:
-        for spec, when in package.provided.items():
+    if pkg.provided:
+        for spec, when in pkg.provided.items():
             print "    %s provides %s" % (when, spec)
     else:
         print "    None"
 
     print
     print "Description:"
-    if package.__doc__:
-        doc = re.sub(r'\s+', ' ', package.__doc__)
-        lines = textwrap.wrap(doc, 72)
-        for line in lines:
-            print "    " + line
+    if pkg.__doc__:
+        print format_doc(pkg, indent=4)
     else:
         print "    None"
+
+
+def info(parser, args):
+     if args.rst:
+         info_rst()
+
+     else:
+         if not args.name:
+             tty.die("You must supply a package name.")
+         pkg = spack.db.get(args.name)
+         info_text(pkg)

var/spack/packages/cmake/package.py

@@ -25,6 +25,8 @@
 from spack import *
 
 class Cmake(Package):
+    """A cross-platform, open-source build system. CMake is a family of
+       tools designed to build, test and package software."""
     homepage  = 'https://www.cmake.org'
     url       = 'http://www.cmake.org/files/v2.8/cmake-2.8.10.2.tar.gz'
 

var/spack/packages/dyninst/package.py

@@ -25,6 +25,8 @@
 from spack import *
 
 class Dyninst(Package):
+    """API for dynamic binary instrumentation.  Modify programs while they
+    are executing without recompiling, re-linking, or re-executing."""
     homepage = "https://paradyn.org"
     url      = "http://www.dyninst.org/sites/default/files/downloads/dyninst/8.1.2/DyninstAPI-8.1.2.tgz"
     list_url = "http://www.dyninst.org/downloads/dyninst-8.x"

var/spack/packages/launchmon/package.py

@@ -25,6 +25,8 @@
 from spack import *
 
 class Launchmon(Package):
+    """Software infrastructure that enables HPC run-time tools to
+       co-locate tool daemons with a parallel job."""
     homepage = "http://sourceforge.net/projects/launchmon"
     url      = "http://downloads.sourceforge.net/project/launchmon/launchmon/1.0.1%20release/launchmon-1.0.1.tar.gz"
 

var/spack/packages/libunwind/package.py

@@ -25,6 +25,8 @@
 from spack import *
 
 class Libunwind(Package):
+    """A portable and efficient C programming interface (API) to determine
+       the call-chain of a program."""
     homepage = "http://www.nongnu.org/libunwind/"
     url      = "http://download.savannah.gnu.org/releases/libunwind/libunwind-1.1.tar.gz"
 

var/spack/packages/scr/package.py

@@ -25,6 +25,9 @@
 from spack import *
 
 class Scr(Package):
+    """SCR caches checkpoint data in storage on the compute nodes of a
+       Linux cluster to provide a fast, scalable checkpoint/restart
+       capability for MPI codes"""
     homepage = "https://computation-rnd.llnl.gov/scr"
     url      = "http://downloads.sourceforge.net/project/scalablecr/releases/scr-1.1-7.tar.gz"
 

var/spack/packages/spindle/package.py

@@ -25,6 +25,11 @@
 from spack import *
 
 class Spindle(Package):
+    """Spindle improves the library-loading performance of dynamically
+       linked HPC applications.  Without Spindle large MPI jobs can
+       overload on a shared file system when loading dynamically
+       linked libraries, causing site-wide performance problems.
+    """
     homepage = "https://computation-rnd.llnl.gov/spindle"
     url      = "https://github.com/hpc/Spindle/archive/v0.8.1.tar.gz"
     list_url = "https://github.com/hpc/Spindle/releases"