Add helpGroup for options and commands

[shadowspawn]

Problem

Some people with larger programs would like to break up their commands and options into groups in the help. There have not been a lot of requests for this, but it is something I had noticed as a possible enhancement.

See: #78 #374 (comment) #1897

Help groups are common in "big" programs, but big programs often have custom help systems anyway! (e.g. git, npm)

Solution

Add .helpGroup() to Command and Option. Use the help groups as titles in the help.

To support built-in features and external commands, add {helpGroup} configuration to:

• .version()
• .helpOption()
• .addHelpCommand()
• external command configuration

program.command('build').helpGroup('Demo Commands:').action(() => {});
program.command('serve', 'external command', { helpGroup: 'Demo Commands:' });
program.addOption(new Option('-e, --example').helpGroup('Demo Options:'));
program.version('1.2.3', '--version', 'Show version', { helpGroup: 'Demo Options:' });
program.helpOption('-s, --support', 'Show help', { helpGroup: 'Demo Options:' });
program.addHelpCommand('help [command]', 'Show help', { helpGroup: 'Demo Commands:' });

% node pr-example.js
Usage: pr-example [options] [command]

Demo Options:
  -e, --example
  --version       Show version
  -s, --support   Show help

Demo Commands:
  build
  serve           external command
  help [command]  Show help

ChangeLog

[sinedied]

Looks interesting, and would perfectly fix my current issue :)

[shadowspawn]

I am still wondering about:

program.version('1.2.3', '--version', 'Show version', { helpGroup: 'Demo Options:' });
program.helpOption('-s, --support', 'Show help', { helpGroup: 'Demo Options:' });
program.addHelpCommand('help [command]', 'Show help', { helpGroup: 'Demo Commands:' });

I want to think a bit more about consistency across the API and whether an options-bag is the best approach.

(And have been busy reviewing other PRs.)

[sinedied]

It's not the prettiest but I can't think of any better alternative, and it makes sense in regard to the existing api.
It's also probably not something that everyone wants to use all the time, so having it as an extra option seems the best approach to me.

[shadowspawn]

(Thanks for comments @sinedied )

[shadowspawn]

If I can't decide for now on a built-in way of customising the version option and help option and help command, could maybe leave it to the author! Thinking of this as an interim work-around rather than permanent solution.

class MyCommand extends Command {
  createCommand(name) {
    const cmd =  new MyCommand(name);

    // Set group on the special built-in command.
    if (cmd.name() === 'help')
      cmd.helpGroup('Demo Commands:');

    return cmd;
  }

  createOption(flags, description) {
    const option = super.createOption(flags, description);

    // Set group on the special built-in options.
    if (option.long === '--version' || option.long === '--help')
      option.helpGroup('Demo Options:');

    return option;
  }
}

[sinedied]

This would be totally fine for me given that's probably an infrequent use case.
Though the . helpGroup() method isn't implemented yet, right?

[shadowspawn]

Though the .helpGroup() method isn't implemented yet, right?

Correct. Still need that work from this PR.

[shadowspawn]

There hasn't been much interest in this feature to date. There is a reasonable chunk of work to do a full solution. Putting this draft away for now.

This issue prompted a couple of refactors so may be easier to customise built-in help option and help command in future: #2006 #2087

I liked "section" approach used in #1897 example implementation which could possibly also help with #1870. (Not included in this draft.)