Enable ember generate <blueprint> --help for individual blueprint docs

[trabus]

This PR fixes #2553, adding the ability to add printDetailedHelp to blueprints.

I've extracted the help logic from lookup-command.js and added a then in the command processing promise chain in cli.js which allows a command to exit before running if the -h or --help option is present. From there the help command is run with the original options passed in (in addition to the command name).

I've added the help option to availableOptions for all commands, which as a side effect lists the --help option as an availableOption for every command. For example:

// with --help added to availableOptions
ember version <options...>
  outputs ember-cli version
  aliases: v, version, -v, --version
  --verbose (Boolean) (Default: false)
  --help (Boolean) (Default: false)
    aliases: -h

// without
ember version <options...>
  outputs ember-cli version
  aliases: v, version, -v, --version
  --verbose (Boolean) (Default: false)

I can remove this if desired, which would go back to the current setup where the --help option is assumed present.

I still need to write tests for this, and I would like to follow this PR up with adding printDetailedHelp to all of the built-in blueprints that could use it. I've mainly put this up for review as I progress on it.

[kimroen]

Some previous discussion and ideas regarding the blueprint-parts of this: #1279 (comment)

[trabus]

I've removed the help option from availableOptions on all commands, as it was breaking tests due to the extra option being printed.

I took an initial crack at the model help text, but it needs some work. Input on this part in particular would be great. I'm thinking that blueprint help should probably have some convenience methods to handle formatting, and that should probably live on the blueprint model somewhere. The current ember g model -h output looks like this:

Requested ember-cli commands:

ember generate <blueprint> <options...>
  Generates new code from blueprints.
  aliases: g
  --dry-run (Boolean) (Default: false)
    aliases: -d
  --verbose (Boolean) (Default: false)
    aliases: -v
  --pod (Boolean) (Default: false)
    aliases: -p

      model <name> <attr:type>
        Generates an ember-data model.
        You may generate models with as many attrs as you would like to pass. The following attribute types are supported:
          <attr-name>
          <attr-name>:array
          <attr-name>:boolean
          <attr-name>:date
          <attr-name>:object
          <attr-name>:number
          <attr-name>:string
          <attr-name>:belongs-to:<model-name>
          <attr-name>:has-many:<model-name>

        For instance: `ember generate model taco filling:belongs-to:protein toppings:has-many:toppings name:string price:number misc`
        would result in the following model:

        import DS from 'ember-data';
        export default DS.Model.extend({
          filling: DS.belongsTo('protein'),
          toppings: DS.hasMany('topping')
          name: DS.attr('string'),
          price: DS.attr('number')
          misc: DS.attr()
        });

[joostdevries]

@trabus This looks nice. Right now, ember points you to use the help command, wouldn't it make more sense to also use ember help generate model instead of ember generate model --help?

[trabus]

Actually ember generate model --help is equivalent to ember help generate model, the --help option exits the command early and turns it into a help command. Both commands work and have the same result.

[joostdevries]

It becomes harder to review the changes because you're changing the syntnax here (moving then to a new line and indenting the block). I'd put that kind of stuff in a separate pr.

[trabus]

I've reverted the formatting for now.

[trabus]

I don't know why appveyor is failing, but it's bailing before even running the tests.

[joostdevries]

I really like the functionality this provides. I'm not sure whether the current JS implementation or a markdown file as suggested in #1279 should be preferred though. I also think we might be able to simplify/clarify the implementation a little bit (to make it more transparent what's happening).
@jgwhite @stefanpenner what do you think?

[trabus]

If we can throw a markdown file in a blueprint, then parse that into color text, I'm absolutely for that (it would be much easier and better than string concatenation like we're currently doing). I'm sure something like that is possible, but I'm not familiar with a way to do it myself.

I like how projects like sails have README.md files in folders for some of the files, and they also use them for their docs I've noticed.

[jgwhite]

Seems like the markdown part could come later, if desirable. This adds lots of value as it currently stands.

[trabus]

Now we just need to go through and add printDetailedHelp to all the blueprints that could use it! ;)

[trabus]

Seems like the markdown part could come later, if desirable. This adds lots of value as it currently stands.

I could see the printDetailedHelp become a builtin method for blueprints that would check for a markdown file, then parse it into terminal output.

[jgwhite]

I could see the printDetailedHelp become a builtin method for blueprints that would check for a markdown file, then parse it into terminal output.

Totally.

Now we just need to go through and add printDetailedHelp to all the blueprints that could use it! ;)

Do you want to add all the detailed help in this PR, or have it happen piecemeal in PRs that follow?

I’d say LGTM and the open it up to the community to drive detailed documentation of blueprints.

[trabus]

Do you want to add all the detailed help in this PR, or have it happen piecemeal in PRs that follow?

I vote piecemeal. Maybe I can get the markdown parsing in sooner than later, and we'd save ourselves from having to write the help docs twice.

[jgwhite]

Cool. LGTM.

Looks like the AppVeyor failure is a problem installing Phantom. Can someone with the keys re-run the build?

[johanneswuerbach]

@jgwhite just submitted #3322 to fix AppVeyor

[jgwhite]

@johanneswuerbach awesome thank you.

[jgwhite]

Can we delete these lines altogether?

[trabus]

What lines?

Sorry, forgot about those after I commented them out. ;)

[trabus]

Rebased and re-ran travis (after a timeout on 0.12). AppVeyor seems okay aside from the timeout, but that's also happening for master.