From 36a87f5bf9884978ba1f672322d9b7f663cf4f58 Mon Sep 17 00:00:00 2001 From: Todd Gamblin Date: Wed, 8 Oct 2014 03:07:54 -0700 Subject: Update documentation to add an auto-generated list of packages. --- lib/spack/docs/.gitignore | 1 + lib/spack/docs/Makefile | 9 +- .../docs/_themes/sphinx_rtd_theme/footer.html | 2 +- lib/spack/docs/conf.py | 2 +- lib/spack/docs/index.rst | 1 + lib/spack/llnl/util/tty/colify.py | 8 +- lib/spack/spack/cmd/info.py | 118 +++++++++++++++++---- 7 files changed, 117 insertions(+), 24 deletions(-) (limited to 'lib') 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 @@ -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." 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 @@

- © Copyright 2013, + © Copyright 2013-2014, Lawrence Livermore National Laboratory.
Written by Todd Gamblin, tgamblin@llnl.gov, 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 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) -- cgit v1.2.3-70-g09d2