diff options
author | Todd Gamblin <tgamblin@llnl.gov> | 2014-10-08 03:07:54 -0700 |
---|---|---|
committer | Todd Gamblin <tgamblin@llnl.gov> | 2014-10-08 03:08:40 -0700 |
commit | 36a87f5bf9884978ba1f672322d9b7f663cf4f58 (patch) | |
tree | 34e3961ca60d9899cd8cd1f26489b9a823342f39 | |
parent | 319b37af0ea84a6ba88d9a6b3a71f17b35c7f0f5 (diff) | |
download | spack-36a87f5bf9884978ba1f672322d9b7f663cf4f58.tar.gz spack-36a87f5bf9884978ba1f672322d9b7f663cf4f58.tar.bz2 spack-36a87f5bf9884978ba1f672322d9b7f663cf4f58.tar.xz spack-36a87f5bf9884978ba1f672322d9b7f663cf4f58.zip |
Update documentation to add an auto-generated list of packages.
-rw-r--r-- | lib/spack/docs/.gitignore | 1 | ||||
-rw-r--r-- | lib/spack/docs/Makefile | 9 | ||||
-rw-r--r-- | lib/spack/docs/_themes/sphinx_rtd_theme/footer.html | 2 | ||||
-rw-r--r-- | lib/spack/docs/conf.py | 2 | ||||
-rw-r--r-- | lib/spack/docs/index.rst | 1 | ||||
-rw-r--r-- | lib/spack/llnl/util/tty/colify.py | 8 | ||||
-rw-r--r-- | lib/spack/spack/cmd/info.py | 118 | ||||
-rw-r--r-- | var/spack/packages/cmake/package.py | 2 | ||||
-rw-r--r-- | var/spack/packages/dyninst/package.py | 2 | ||||
-rw-r--r-- | var/spack/packages/launchmon/package.py | 2 | ||||
-rw-r--r-- | var/spack/packages/libunwind/package.py | 2 | ||||
-rw-r--r-- | var/spack/packages/scr/package.py | 3 | ||||
-rw-r--r-- | var/spack/packages/spindle/package.py | 5 |
13 files changed, 133 insertions, 24 deletions
diff --git a/lib/spack/docs/.gitignore b/lib/spack/docs/.gitignore index 4d5300fbb9..7701dd9f12 100644 --- a/lib/spack/docs/.gitignore +++ b/lib/spack/docs/.gitignore @@ -1,2 +1,3 @@ +package_list.rst spack*.rst _build diff --git a/lib/spack/docs/Makefile b/lib/spack/docs/Makefile index 4baba720ef..4d71c2052e 100644 --- a/lib/spack/docs/Makefile +++ b/lib/spack/docs/Makefile @@ -22,6 +22,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." diff --git a/lib/spack/docs/_themes/sphinx_rtd_theme/footer.html b/lib/spack/docs/_themes/sphinx_rtd_theme/footer.html index 0eccd11178..5ec315e58f 100644 --- a/lib/spack/docs/_themes/sphinx_rtd_theme/footer.html +++ b/lib/spack/docs/_themes/sphinx_rtd_theme/footer.html @@ -13,7 +13,7 @@ <hr/> <p> - © Copyright 2013, + © 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 diff --git a/lib/spack/docs/conf.py b/lib/spack/docs/conf.py index 700cb00299..b4d49c594d 100644 --- a/lib/spack/docs/conf.py +++ b/lib/spack/docs/conf.py @@ -90,7 +90,7 @@ master_doc = 'index' # 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 diff --git a/lib/spack/docs/index.rst b/lib/spack/docs/index.rst index ac0eac93f3..73eff43ab7 100644 --- a/lib/spack/docs/index.rst +++ b/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 diff --git a/lib/spack/llnl/util/tty/colify.py b/lib/spack/llnl/util/tty/colify.py index 5586b2681a..ff06241937 100644 --- a/lib/spack/llnl/util/tty/colify.py +++ b/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 diff --git a/lib/spack/spack/cmd/info.py b/lib/spack/spack/cmd/info.py index bb147b30f5..c86dcac2f5 100644 --- a/lib/spack/spack/cmd/info.py +++ b/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) diff --git a/var/spack/packages/cmake/package.py b/var/spack/packages/cmake/package.py index ca6553df84..890af9baa9 100644 --- a/var/spack/packages/cmake/package.py +++ b/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' diff --git a/var/spack/packages/dyninst/package.py b/var/spack/packages/dyninst/package.py index 069237f7ff..df19ac7bc0 100644 --- a/var/spack/packages/dyninst/package.py +++ b/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" diff --git a/var/spack/packages/launchmon/package.py b/var/spack/packages/launchmon/package.py index b6773a85bc..bdf988bdd3 100644 --- a/var/spack/packages/launchmon/package.py +++ b/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" diff --git a/var/spack/packages/libunwind/package.py b/var/spack/packages/libunwind/package.py index aeadc85eb3..239fcbcfd5 100644 --- a/var/spack/packages/libunwind/package.py +++ b/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" diff --git a/var/spack/packages/scr/package.py b/var/spack/packages/scr/package.py index d480dba62f..d456ecaba0 100644 --- a/var/spack/packages/scr/package.py +++ b/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" diff --git a/var/spack/packages/spindle/package.py b/var/spack/packages/spindle/package.py index bb0b74ab6f..fd59282ebb 100644 --- a/var/spack/packages/spindle/package.py +++ b/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" |