Skip to content

Rework Spack help.#3033

Merged
tgamblin merged 7 commits intodevelopfrom
features/better-help
May 8, 2017
Merged

Rework Spack help.#3033
tgamblin merged 7 commits intodevelopfrom
features/better-help

Conversation

@tgamblin
Copy link
Copy Markdown
Member

@tgamblin tgamblin commented Feb 5, 2017

Reworks the top-level Spack help to be more helpful.

Tasks:

  • Add ability to print simplified command groups
  • Add short and long help
  • Add epilogue to direct user to the various help commands.
  • Finalize sections for short and long help
  • Move most of bin/spack to spack.main.main method
  • Lazy command loading (commands not loaded unless needed)
  • spack docs command opens docs in a browser
  • move spec syntax help to spack help --spec, expand examples

There are now three ways to get help:

  • spack help / spack -h: default short help for basic usage, with commands broken into some simple sections.
  • spack help -a: help on everything, with more commands broken into more sections.
  • spack help --spec: show help on the spec syntax
  • spack docs: open the spack help in a web browser.

The default spack help now looks like this:

$ spack -h
usage: spack [-hkV] <command> [...]

A flexible package manager that supports multiple versions,
configurations, platforms, and compilers.

These are common spack commands:

query packages:
  list            list and search available packages
  info            get detailed information on a particular package
  find            list and search installed packages

build packages:
  install         build and install packages
  uninstall       remove installed packages
  spec            show what would be installed, given a spec

environment:
  load            add package to environment using `module load`
  module          manipulate module files
  unload          remove package from environment using `module unload`
  view            produce a single-rooted directory view of packages

create packages:
  create          create a new package file
  edit            open package files in $EDITOR

system:
  arch            print architecture information about this machine
  compilers       list available compilers

optional arguments:
  -h, --help      show this help message and exit
  -k, --insecure  do not check ssl certificates when downloading
  -V, --version   show version number and exit

more help:
  spack help -a          list all available commands
  spack help <command>   help on a specific command
  spack help --spec      help on the spec syntax
  spack docs             open http://spack.rtfd.io/ in a browser

And spack help --all looks like this:

$ spack help -a
usage: spack [-hdDkmpPlinesvsV] <command> [...]

A flexible package manager that supports multiple versions,
configurations, platforms, and compilers.

Complete list of spack commands:

administration:
  bootstrap             create a new installation of spack in another prefix
  purge                 remove temporary build files and/or downloaded archives
  reindex               rebuild Spack's package database

query packages:
  list                  list and search available packages
  info                  get detailed information on a particular package
  find                  list and search installed packages
  dependents            show installed packages that depend on another
  graph                 generate graphs of package dependency relationships
  providers             list packages that provide a particular virtual package

build packages:
  fetch                 fetch archives for packages
  stage                 expand downloaded archive in preparation for install
  patch                 patch expanded archive sources in preparation for install
  configure             stage and configure a package but do not install
  build                 stops at build stage when installing a package, if possible
  restage               revert checked out package source code
  install               build and install packages
  uninstall             remove installed packages
  clean                 remove build stage and source tarball for packages
  env                   show install environment for a spec, and run commands
  spec                  show what would be installed, given a spec

configuration:
  config                get and set configuration options
  mirror                manage mirrors
  repo                  manage package source repositories

developer:
  debug                 debugging commands for troubleshooting Spack
  diy                   do-it-yourself: build from an existing source directory
  flake8                runs source code style checks on Spack. requires flake8
  pkg                   query packages associated with particular git revisions
  pydoc                 run pydoc from within spack
  python                launch an interpreter as spack would launch a command
  setup                 create a configuration script and module, but don't build
  test                  run spack's unit tests
  url                   debugging tool for url parsing

environment:
  cd                    cd to spack directories in the shell
  load                  add package to environment using `module load`
  location              print out locations of various directories used by Spack
  module                manipulate module files
  unload                remove package from environment using `module unload`
  unuse                 remove package from environment using dotkit
  use                   add package to environment using dotkit
  view                  produce a single-rooted directory view of packages

extensions:
  activate              activate a package extension
  deactivate            deactivate a package extension
  extensions            list extensions for package

create packages:
  checksum              checksum available versions of a package
  create                create a new package file
  edit                  open package files in $EDITOR
  md5                   calculate md5 checksums for files/urls
  versions              list available versions of a package

system:
  arch                  print architecture information about this machine
  compiler              manage compilers
  compilers             list available compilers

optional arguments:
  -h, --help            show this help message and exit
  -d, --debug           write out debug logs during compile
  -D, --pdb             run spack under the pdb debugger
  -k, --insecure        do not check ssl certificates when downloading
  -m, --mock            use mock packages instead of real ones
  -p, --profile         profile execution using cProfile
  -P STAT, --sorted-profile STAT
                        profile and sort by one or more of:
                        [cumulative, module, ncalls, pcalls, file, line, name,
                         calls, stdname, nfl, filename, cumtime, time, tottime]
  --lines LINES         lines of profile output; default 20; or 'all'
  -v, --verbose         print additional output during builds
  -s, --stacktrace      add stacktraces to all printed statements
  -V, --version         show version number and exit

more help:
  spack help -a          list all available commands
  spack help <command>   help on a specific command
  spack help --spec      help on the spec syntax
  spack docs             open http://spack.rtfd.io/ in a browser

Help contents

Commands now provide three properties that are used to auto-generate the help output:

description = "description of this command"
section = "developer"
level = "long"

section controls the top-level help sections in the help output, and level controls what goes in short or long help.

main.py

Most of the complicated part of bin/spack has been moved into lib/spack/spack/main.py, which contains the main(args) method, which can be called programmatically. It returns an exit code. bin/spack now just handles setting up the system path, and then it hands off to the spack package.

There are some controls for main.py that let us override the default alphabetical command order and names of sections, so we can fine-tune the help output for clarity.

Lazy command loading

Previously, spack would build a complete parser for all commands every time it is run. This means we have to load all the commands, which is a lot of python files.

main.py is a little fancier -- it builds a minimal parser with a dummy argument first, and loads only the needed command. This can speed things like spack location up, even on my laptop with SSD:

develop:

$ time for i in $(seq 1 100); do spack location -i libelf > /dev/null; done

real	0m32.309s
user	0m22.511s
sys	0m8.871s

features/better-help:

$ time for i in $(seq 1 100); do spack location -i libelf > /dev/null; done

real	0m23.653s
user	0m15.879s
sys	0m6.991s

Spack only ever loads all the commands when they're needed to build the full help output.

spack docs

There is now a spack docs command that opens the spack docs in your browser. That, the docs URL, and all the other help commands are described prominently at the bottom of the default spack -h output.

@citibeth
Copy link
Copy Markdown
Member

citibeth commented Feb 6, 2017

This promises to bring some order to the chaos! :-)

There are now three basic ways to get help:

spack and spack --help should also do something reasonable.

spack help

basic usage:

Try this order: list, info, install, uninstall, find. Break out compilers and arch into a new section.

Order the overal sections as: basic usage, environment, packaging, app developers. Rename app developers to application developers, app sounds too much like you're making things for iPhone.

spack help --all should be listed as a subcommand under spack -h, otherwise no one will know it exists. Maybe make it prominent... For more help, try spack help --all.

If it doesn't already, spack help should send to stdout. I can't stand programs where you have to type mycommand --help 2>&1 | less.

Subcommands should stay under the same heading in spack help vs. spack help --all. For example, arch moved.

The new sections on spack help --all should come AFTER the sections already displayed on spack help. Or... since sections seem to grow moving to --all, consider printing "basic" subcommands (those available in spack help) in bold/color, and other subcommands in non-bold. However, this should still work for the naive user who writes spack help | less without doing any color-related Less aliases.

spack help --spec

How was a user to ever know about this sub-subcommand? Really.. the original spack help should print out all variants that are available under spack help. Also, spack help --spec should give a little more background text on what a spec is, etc.

Copy link
Copy Markdown
Member

@citibeth citibeth left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Should there be an inversion of control here? i.e. when a subcommand is defined, you declare at that point in the code (a) which section it belongs in, and (b) whether it should be included in basic vs. extended help? I think that would be more maintainable than the structure here.

@adamjstewart
Copy link
Copy Markdown
Member

Try this order: list, info, install, uninstall, find.

👍

Break out compilers and arch into a new section.

Maybe call it "setup"? Also, does anyone even use spack arch except for debugging weird Spack bugs? I definitely wouldn't say it's a commonly used command. Maybe move that to --all.

Maybe make it prominent... For more help, try spack help --all.

❤️

@tgamblin
Copy link
Copy Markdown
Member Author

tgamblin commented Feb 7, 2017

@citibeth @adamjstewart: thanks for the feedback. I like all these suggestions.

@citibeth

Should there be an inversion of control here? i.e. when a subcommand is defined, you declare at that point in the code (a) which section it belongs in, and (b) whether it should be included in basic vs. extended help? I think that would be more maintainable than the structure here.

Agree. How do you recommend controlling the order in which commands appear? We could add section, advanced, and priority fields and us the priority to order things in sections. I generally find it cumbersome to maintain keys like that, but I do like having the section/difficulty metadata in the commands themselves.

@citibeth
Copy link
Copy Markdown
Member

citibeth commented Feb 7, 2017 via email

@tgamblin tgamblin force-pushed the features/better-help branch from 461ac47 to 8cba63a Compare May 8, 2017 07:19
@tgamblin tgamblin added commands documentation Improvements or additions to documentation performance user-experience labels May 8, 2017
@tgamblin tgamblin force-pushed the features/better-help branch 2 times, most recently from 7409556 to 4333f11 Compare May 8, 2017 07:40
- Full help is now only generated lazily, when needed.
  - Executing specific commands doesn't require loading all of them.
  - All commands are only loaded if we need them for help.

- There is now short and long help:
  - short help (spack help) shows only basic spack options
  - long help (spack help -a_ shows all spack options
  - Both divide help on commands into high-level sections

- Commands now specify attributes from which help is auto-generated:
  - description: used in help to describe the command.
  - section: help section
  - level: short or long

- Clean up command descriptions
- Add a `spack docs` command to open full documentation in the browser.
@tgamblin tgamblin force-pushed the features/better-help branch from 4333f11 to b29122b Compare May 8, 2017 07:42
@tgamblin
Copy link
Copy Markdown
Member Author

tgamblin commented May 8, 2017

Ok @citibeth @alalazo @adamjstewart: I think this is done.

  • Help is reworked
  • control is inverted: commands say what section/help level they're in
  • most of bin/spack is moved to spack.main
  • there are controls in spack.main to fine-tune the ordering of commands in the help
  • The full Spack argparse parser is generated lazily, so that all 53 commands aren't loaded every time we run spack (only when full help is needed)
  • spack -h directs users to spack help -a, spack help <command>, and spack docs
  • help output mentions the documentation website.

I got rid of spack help --spec for now, as I think if we want to add guides we should do it properly. The spec help wasn't all that intuitive or useful, and directing users to the docs should cover it.

Note that the lazy loading speeds up all spack commands -- we don't have to load all the .py files anymore. I think this will be more noticeable on clusters than on my laptop, but you can see it makes a difference even on the laptop.

Thoughts?

@tgamblin
Copy link
Copy Markdown
Member Author

tgamblin commented May 8, 2017

FYI: for more detail, see the PR description. I reworked it to include the various new features.

Copy link
Copy Markdown
Member

@alalazo alalazo left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is great! The improvements on spack help are evident, and now the help is clean and tidy. Things I liked most:

  • Subsections are presented in the order they are needed
  • Developers help is hidden by default

I think it's a "must merge immediately". Found just a minor point in _main.

main(sys.argv)
# Once we've set up the system path, run the spack main method
import spack.main # noqa
sys.exit(spack.main.main())
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think the clean-up here is remarkable, and will probably also help with #1385

In a normal Spack installation, this is invoked from the bin/spack script
after the system path is set up.
"""
from __future__ import print_function
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This python module is also quite an improvement over the previous state of things!

return_val = command(parser, args)
except SpackError as e:
e.die() # gracefully die on any SpackErrors
except KeyboardInterrupt:
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think here we lost a couple of lines in rebase:

except Exception as e:
    tty.die(str(e))

@tgamblin tgamblin force-pushed the features/better-help branch from 0dab7e8 to 46cf615 Compare May 8, 2017 14:12
@@ -24,6 +24,8 @@
##############################################################################

description = "run pydoc from within spack"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We now have 2 commands, spack doc and spack docs. Based on the name alone, it's impossible to guess what each command does and how they differ. Can we rename spack doc? What does spack doc even do?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

It just runs pydoc (aka help()) within the Spack system path. e.g., try: spack doc spack.spec.Spec

How about spack pydoc?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ooh, this is very interesting. Yeah, spack pydoc sounds better to me. Can you add documentation on both of these commands to the Developer Guide? Just a single paragraph blurb and an example for running spack pydoc.


description = "print architecture information about this machine"
section = "system"
level = "short"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still haven't decided whether spack arch should be long or short. It's not commonly used anymore now that we switched to distro and most distributions are detected correctly.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We can always change it later. Personally I think people want to know what their architecture is.

from spack.cmd import display_specs

description = "find installed spack packages"
description = "query and show installed packages"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think I like the old description better. It solidifies the idea that spack find is for "finding" installed packages. A lot of new users confuse spack find and spack list because other packages managers use them for the reverse meanings. I'm not suggesting we rename these commands, at least not in this PR. But we should consider what other package managers use and if we differ from them we need to make it abundantly clear. I'll open up a separate issue to discuss naming of commands.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

See #4159 for potential flame wars on command renaming.

help='command to get help on')
help_cmd_group = subparser.add_mutually_exclusive_group()
help_cmd_group.add_argument('help_command', nargs='?', default=None,
help='command to get help on')
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I'm not sure I understand. Mutually exclusive groups generally have multiple options, only one of which can be used at the same time. Here you have 2 mutually exclusive groups. Did you mean to make one mutually exclusive group so that you can either run spack help <command> or spack help --all but not both?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch. There used to be spack help --spec, which was mutually exclusive from the others. It's gone now.


description = "build and install packages"
section = "basic"
level = "short"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

In the context of spack help --all, it makes more sense for install and uninstall to go in Building.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want it to be possible to move commands? I went for simple -- i.e., @citibeth's recommendation that things not move between short and long help, and the recommendation that commands only be in one section. Is it worth it to change those restrictions?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I was actually proposing that install and uninstall be moved to Building for both short and long descriptions.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Would you call basic usage something else in that case? I was trying to group the most important commands under basic usage.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Nah, I would keep basic usage the same. building would be the next section so they don't have to travel far to see what they want.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I would keep them in basic usage. What is more basic in Spack than installing and uninstalling stuff?

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Copy link
Copy Markdown
Member Author

@tgamblin tgamblin May 8, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ok I actually tried this. I changed basic to query packages and it seems to work -- I like it. Update coming. install/uninstall/spec are the only build commands shown in the top-level help so it is still very clear.

from llnl.util.tty.colify import colify

description = "print available spack packages to stdout in different formats"
description = "query and show packages that can be installed"
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Based on my comment above, it might be better to say "list available packages". But I get that you want to make it clear that spack list can also accept an argument for searching.

'extensions': 'extensions',
'help': 'further help',
'packaging': 'packaging',
'system': 'system',
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Use Camel Case for these. For example:

Basic Usage

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Well, that's title case (because it has spaces), but sure.

I actually tried this, and here are the issues: "optional arguments" and "positional arguments" section headers are still lowercase due to being build into argparse, and getting rid of them is a pain. I tried overriding them in the constructor for SpackArgumentParser, and if you do that, the help argument still ends up in the original optional arguments group, and your arguments end up in the Optional Arguments group.

Also, we print the description field at the top of spack help <command>, and it looks weird to have that be lowercase and the section headers in title case. So I went with what argparse does and tried to stick to lowercase everywhere.

How important is this one to you?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, good point. Keep them lowercase then. I made the same change in #2847 because I noticed that the default --help messages were also lowercase.

Copy link
Copy Markdown
Member Author

@tgamblin tgamblin May 8, 2017

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cool. We can revisit this later if we want. But argparse is really nasty and I'm trying to avoid modifying its internals. The argparse package we have in external is a backport to support 2.6; nothing custom. I'd rather keep it that way.

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Agreed. There is actually a way to override these things without hacking argparse, but I'd rather not do it just to make things capitalized.

section_order = {
'basic': ['list', 'info', 'install', 'uninstall', 'find'],
'build': ['fetch', 'stage', 'patch', 'configure', 'build', 'clean',
'restage']
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I mentioned above, it seems silly that install and uninstall aren't in this list.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Do you want them in both lists, or do you want install to move between sections depending on short or long help?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think it makes more sense to always have them in build for both short and long. I know this adds a build group to the short help message. But it makes a lot more sense for the long help message.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

So, this brings up a question of what the help should say when we start having binary packages. In that case, install may default to installing a signed binary. Should it still go in build? What's a good section title that covers all that?

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Hmm. I don't know enough about the binary install plans. Wouldn't it install binaries if they are available and build from source if not? I think that's how Homebrew does it. I wouldn't want 2 commands for that.

Copy link
Copy Markdown
Member Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yes. I'm just pointing out that if you stick it in a section called "building" that might be confusing. But maybe we can deal with that when we come to it.

@adamjstewart
Copy link
Copy Markdown
Member

I got rid of spack help --spec for now, as I think if we want to add guides we should do it properly. The spec help wasn't all that intuitive or useful, and directing users to the docs should cover it.

I actually liked this part of the help message. For the first month of using Spack, I would refer to it when I was trying to remember what order things should go in (apparently order is sometimes important?). And it made sense that it was a recursive definition where each spec could depend on another spec with the same attributes.

@tgamblin
Copy link
Copy Markdown
Member Author

tgamblin commented May 8, 2017

@adamjstewart: do you want to bring it back? I don't mind doing it, but where would you put it? Top of basic help? Bottom before the further help part? Separate command?

@adamjstewart
Copy link
Copy Markdown
Member

@tgamblin How about top (or bottom) of long help? That way it doesn't clutter the short help. spack help --spec would also be fine.

@tgamblin
Copy link
Copy Markdown
Member Author

tgamblin commented May 8, 2017

@adamjstewart @alalazo: Ok, I've updated (see above) and re-added spack help --spec. It now looks like this:

$ spack help --spec
spec expression syntax:

  package [constraints] [^dependency [constraints] ...]

  package                           any package from 'spack list'

  constraints:
    versions:
      @version                      single version
      @min:max                      version range (inclusive)
      @min:                         version <min> or higher
      @:max                         up to version <max> (inclusive)

    compilers:
      %compiler                     build with <compiler>
      %compiler@version             build with specific compiler version
      %compiler@min:max             specific version range (see above)

    variants:
      +variant                      enable <variant>
      -variant or ~variant          disable <variant>
      variant=value                 set non-boolean <variant> to <value>
      variant=value1,value2,value3  set multi-value <variant> values

    architecture variants:
      target=target                 specific <target> processor
      os=operating_system           specific <operating_system>
      platform=platform             linux, darwin, cray, bgq, etc.
      arch=platform-os-target       shortcut for all three above

    cross-compiling:
      os=backend or os=be           build for compute node (backend)
      os=frontend or os=fe          build for login node (frontend)

    dependencies:
      ^dependency [constraints]     specify constraints on dependencies

  examples:
      hdf5                          any hdf5 configuration
      hdf5 @1.10.1                  hdf5 version 1.10.1
      hdf5 @1.8:                    hdf5 1.8 or higher
      hdf5 @1.8: %gcc               hdf5 1.8 or higher built with gcc
      hdf5 +mpi                     hdf5 with mpi enabled
      hdf5 ~mpi                     hdf5 with mpi disabled
      hdf5 +mpi ^mpich              hdf5 with mpi, using mpich
      hdf5 +mpi ^[email protected]        hdf5 wtih mpi, using openmpi 1.7
      boxlib dim=2                  boxlib built for 2 dimensions
      libdwarf %intel ^libelf%gcc
          libdwarf, built with intel compiler, linked to libelf built with gcc
      mvapich2 %pgi fabrics=psm,mrail,sock
          mvapich2, built with xl compiler, with support for multiple fabrics

@alalazo
Copy link
Copy Markdown
Member

alalazo commented May 8, 2017

mvapich2 %pgi fabrics=psm,mrail,sock
mvapich2, built with xl compiler, with support for multiple fabrics

with pgi compiler

@tgamblin
Copy link
Copy Markdown
Member Author

tgamblin commented May 8, 2017

@alalazo @adamjstewart: I updated the spack -h and spack help -a output above.

basic usage is now query packages, and build pipeline is now building packages. I think it is reasonable clear. With the extra section and the tightened (but vertically longer) more help section, I think this is about as long as the basic help should be.

Thoughts? I like the prior basic usage and the current set of sections about the same. The current layout is more logically correct to me and apparently also @adamjstewart.

@tgamblin tgamblin force-pushed the features/better-help branch from c9f1f22 to c9c4609 Compare May 8, 2017 18:28
libdwarf @g{%intel} ^libelf@g{%gcc}
libdwarf, built with intel compiler, linked to libelf built with gcc
mvapich2 @g{%pgi} @B{fabrics=psm,mrail,sock}
mvapich2, built with pgi compiler, with support for multiple fabrics
Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This is awesome, especially the examples. I can't wait to see all of this in color!

@tgamblin tgamblin merged commit ff3b5d8 into develop May 8, 2017
@adamjstewart adamjstewart deleted the features/better-help branch May 8, 2017 20:20
@adamjstewart adamjstewart mentioned this pull request May 9, 2017
2 tasks
diaena pushed a commit to diaena/spack that referenced this pull request May 26, 2017
- Full help is now only generated lazily, when needed.
  - Executing specific commands doesn't require loading all of them.
  - All commands are only loaded if we need them for help.

- There is now short and long help:
  - short help (spack help) shows only basic spack options
  - long help (spack help -a) shows all spack options
  - Both divide help on commands into high-level sections

- Commands now specify attributes from which help is auto-generated:
  - description: used in help to describe the command.
  - section: help section
  - level: short or long

- Clean up command descriptions

- Add a `spack docs` command to open full documentation
  in the browser.

- move `spack doc` command to `spack pydoc` for clarity

- Add a `spack --spec` command to show documentation on 
  the spec syntax.
xavierandrade pushed a commit to xavierandrade/spack that referenced this pull request Jun 16, 2017
- Full help is now only generated lazily, when needed.
  - Executing specific commands doesn't require loading all of them.
  - All commands are only loaded if we need them for help.

- There is now short and long help:
  - short help (spack help) shows only basic spack options
  - long help (spack help -a) shows all spack options
  - Both divide help on commands into high-level sections

- Commands now specify attributes from which help is auto-generated:
  - description: used in help to describe the command.
  - section: help section
  - level: short or long

- Clean up command descriptions

- Add a `spack docs` command to open full documentation
  in the browser.

- move `spack doc` command to `spack pydoc` for clarity

- Add a `spack --spec` command to show documentation on 
  the spec syntax.
EmreAtes pushed a commit to EmreAtes/spack that referenced this pull request Jul 10, 2017
- Full help is now only generated lazily, when needed.
  - Executing specific commands doesn't require loading all of them.
  - All commands are only loaded if we need them for help.

- There is now short and long help:
  - short help (spack help) shows only basic spack options
  - long help (spack help -a) shows all spack options
  - Both divide help on commands into high-level sections

- Commands now specify attributes from which help is auto-generated:
  - description: used in help to describe the command.
  - section: help section
  - level: short or long

- Clean up command descriptions

- Add a `spack docs` command to open full documentation
  in the browser.

- move `spack doc` command to `spack pydoc` for clarity

- Add a `spack --spec` command to show documentation on 
  the spec syntax.
@tgamblin tgamblin added this to the v0.11.0 milestone Nov 12, 2017
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants