feat: help improvements and customizability by amphro · Pull Request #184 · oclif/core

amphro · 2021-06-10T04:21:00Z

Command and Flag Summary

Oclif will use the first line of command.description as the "summary" which is used as the first line on command help as well as in the command list. This is clever, but can also be hidden and confusing. There is now a summary property on command and flag, which if provided, will be used as the first line on command help and in the command list. It will also be repeated in the DESCRIPTION section of help for increased usability.

The summary property should be one line.

Flag Descriptions

Multiline flag descriptions can be hard to read in a wrapped list view. Oclif will render the list different if there is one descriptions is more than 4 lines, but at that point it may be too late. Not only that, it can still be useful to have a short, easy to digest flag list, with more description down below. Now the summary property on flag, if provided, will be used in the in the flag list and the description will be put in an extended section down below.

FLAGS
  -e, --target-env=<value>...  [default: dsfr] Environment name or alias to open.
  ...

DESCRIPTION
   ...

EXAMPLES
  ...

FLAG DESCRIPTIONS
  -e, --target-env=<value>...

    Specify the login user or alias that’s associated with the environment. For scratch orgs, the login user is generated
    by the command that created the scratch org. You can also set an alias for the scratch org when you create it.

    For Dev Hubs, sandboxes, and production orgs, specify the alias you set when you logged into the org with "sf login".

Flag Help Groups

Help for commands with a large number of flags can be hard to read. It can be hard to pick out related flags. Or it can be hard to pick out flags that may not be directly related to the command, such as flags added by a CLI or a particular plugin. For example, --json or table flags.

Flag help groups help solve this.

FLAGS
  --[no-]opt  my boolean optional flag

TABLE FLAGS
  -x, --extended          show extra columns
  --columns=columns       only show provided columns (comma-separated)
  --csv                   output is csv format [alias: --output=csv]
  --filter=filter         filter property by partial string matching, ex: name=foo
  --hidden                show hidden commands
  --no-header             hide table header from output
  --no-truncate           do not truncate output to fit screen
  --output=csv|json|yaml  output in a more machine friendly format
  --sort=sort             property to sort by (prepend '-' for descending)

CLI FLAGS
  --json  format output as json

Refactor help and extend customizability

There are time where a CLI may just want to add an extra help section or change a section heading in the command help. Or maybe the CLI wants to override the help options. With oclif@1, a CLI could really only override the Help class which did not provide any helpful methods for command help or options. Now, the CommandHelp class is loaded from the Help class so it can be extended. Also, help options can be defined in pjson.oclif.helpOptions. See test/help/show-customized-help.test.ts.

In addition, code like wrap(body, this.opts.maxWidth - spacing, {hard: true, trim: false} and creating a section with [bold(header), indent(body, 2)].join('\n') was called all over the place. These have been abstracted into a base class which all help classes now extend, providing those utilities to custom help classes as well.

Example Descriptions

Having a list of examples with no descriptions is not very useful, which the existing example structure encourages. Consumers can add descriptions themselves but it is less than idea.

Flag.string({
  description: 'my flag',
  examples: [
    'happy path\n<%= config.bin %> <%= command.id %> --flag'
    'run with foo bar\n<%= config.bin %> <%= command.id %> --flag --foo=bar'
  ]
})

Now, examples can be an object {description, command} which will be formatted appropriately. If a sting is provided, it will try to figure our what is a description and what is a command to format in a more readable output.

EXAMPLES
  happy path:

    $ bin command --flag

  run with foo bar:

    $ bin command --flag --foo=bar

amphro · 2021-06-10T04:27:38Z

+    return indent(body, spacing)
+  }
+
+  public renderList(input: (string | undefined)[][], opts: {indentation: number; multiline?: boolean; stripAnsi?: boolean; spacer?: string}): string {


This method is unchanged, just brought over from list.ts.

mdonnalley · 2021-06-11T14:33:47Z

+   * `config=Interfaces.Config` or `opts=Interface.HelpOptions`.
+   *
+   * ```javascript
+   * '<%= config.bin =>` // will resolve to the bin defined in `pjson.oclif`.


I think you meant to have a ` here instead of a '

mdonnalley · 2021-06-11T14:37:32Z

+  /**
+   * An array of examples to show at the end of the command's help.
+   *
+   * IF only a string is provide, it will try to look for a line that starts


Is this worth mentioning in the migration doc?

mdonnalley

Found one issue while testing:

In the messages.md folder I have:

# examples

- happy path example\n<%= config.bin %> <%= command.id %> --jwt-key-file myorg.key --username me@salesforce.com --clientid XXXX

But the help shows:

EXAMPLES
  happy path example\nsf login org jwt --jwt-key-file myorg.key --username me@salesforce.com --clientid XXXX

I noticed that the FLAG DESCRIPTIONS didn't behave as I expected: When I added a summary to one of my flags, I expected to see the new section in help but I didn't. I had to make sure that my description was also multiple lines in order to see the new section. I think my preference is to always add the FLAG DESCRIPTIONS section if the summary prop exists - regardless of whether or not my description is long enough
I think the FLAGS and CLI FLAGS distinction is unclear. I feel like there's a better way to communicate "these flags are specific to this command, and these other flags are generally available on all commands"
Lastly, if I understand correctly consumers have to implement flag groups on their own? Would it better to simply expose that as part of the flag options, e.g.

    alias: Flags.string({
      description: messages.getMessage('alias'),
      group: 'foo',
    }),
    clientid: Flags.string({
      description: messages.getMessage('clientId'),
      group: 'bar',
    }),

amphro · 2021-06-14T21:42:40Z

You can't have \n in markdown since markdown is just text. Just hit enter, or if you want to use \n use a js or ts file instead.
I agree. Fixed and added a test.
Suggestions? I changed to "GLOBAL FLAGS" but I'm impartial.
That is exactly how it is done. See how the --json flag

  alias: Flags.string({
      description: messages.getMessage('alias'),
      helpGroup: 'foo',
  }),
  clientid: Flags.string({
      description: messages.getMessage('clientId'),
      helpGroup: 'bar',
  }),

RodEsp

Consider changing all the references to \n for EOL for windows compatibility?

Co-authored-by: Rodrigo Espinosa de los Monteros <1084688+RodEsp@users.noreply.github.com>

RodEsp · 2021-06-15T22:31:45Z

-    const title = command.description && this.render(command.description).split('\n')[0]
-    if (title) console.log(title + '\n')
+    const summary = this.summary(command) // command.description && this.render(command.description).split('\n')[0]
+    if (summary) console.log(summary + '\n')


This is still pulling from the command description, not the summary but I can't understand why.

This test exemplifies what I mean
#186

RodEsp · 2021-06-15T22:32:18Z

+  protected summary(c: Interfaces.Command): string {
+    if (c.summary) return this.render(c.summary.split('\n')[0])
+
+    return this.render((c.description || '').split('\n')[0])


I believe this should be c.summary but for some reason the .summary isn't being added to the command. See comment above.

Suggested change

return this.render((c.description || '').split('\n')[0])

return this.render((c.summary|| '').split('\n')[0])

I don't know if this is related but .\bin\dev commandreference generate seems to not be able to find .name in here when this branch is yarn linked.

So it's like it's not getting the .plugin property here.

RodEsp

Super long flag descriptions don't align correctly on Windows. They just continue on a newline at the same indentation as the flags.

This reverts commit 3a9c434.

RodEsp · 2021-06-17T14:24:27Z


    const body = flagsWithExtendedDescriptions.map(flag => {
-      return `${this.flagHelpLabel(flag, true)}  ${flag.summary}\n\n${this.indent(this.wrap(flag.description || '', this.indentSpacing * 2))}`
+      // Guaranteed to be set because of the filter above, but make ts happy


amphro requested review from RodEsp and mdonnalley June 10, 2021 04:21

amphro commented Jun 10, 2021

View reviewed changes

mdonnalley approved these changes Jun 11, 2021

View reviewed changes

mdonnalley self-requested a review June 11, 2021 14:50

mdonnalley requested changes Jun 11, 2021

View reviewed changes

amphro added 3 commits June 14, 2021 14:42

feat: help improvments and customizability

a66821d

feat: allow usage title override

374da8b

chore: code review

1fcf290

amphro force-pushed the td/help branch from 3016f6b to 1fcf290 Compare June 14, 2021 21:42

RodEsp reviewed Jun 15, 2021

View reviewed changes

Comment thread src/command.ts Outdated

Comment thread src/help/command.ts Outdated

Comment thread src/help/command.ts Outdated

amphro and others added 3 commits June 15, 2021 15:08

chore: typo

f70b18a

Co-authored-by: Rodrigo Espinosa de los Monteros <1084688+RodEsp@users.noreply.github.com>

chore: use EOL

947e6e3

Co-authored-by: Rodrigo Espinosa de los Monteros <1084688+RodEsp@users.noreply.github.com>

chore: use EOL

413892c

Co-authored-by: Rodrigo Espinosa de los Monteros <1084688+RodEsp@users.noreply.github.com>

RodEsp suggested changes Jun 15, 2021

View reviewed changes

chore: use EOL

3a9c434

RodEsp suggested changes Jun 16, 2021

View reviewed changes

amphro added 5 commits June 16, 2021 08:33

Revert "chore: use EOL"

ae44f55

This reverts commit 3a9c434.

chore: add eol import

fcb111e

chore: try to fix window newline

0a02281

chore: fix found issues with dummary

a642a35

chore: fix broken build

f6fab79

RodEsp reviewed Jun 17, 2021

View reviewed changes

RodEsp approved these changes Jun 17, 2021

View reviewed changes

RodEsp merged commit cb2109b into master Jun 17, 2021

RodEsp deleted the td/help branch June 17, 2021 14:33

shadowspawn mentioned this pull request Jul 17, 2023

Add support for custom help groups tj/commander.js#1897

Closed

	return this.render((c.description \|\| '').split('\n')[0])
	return this.render((c.summary\|\| '').split('\n')[0])

Conversation

amphro commented Jun 10, 2021

Command and Flag Summary

Flag Descriptions

Flag Help Groups

Refactor help and extend customizability

Example Descriptions

Uh oh!

amphro Jun 10, 2021

Choose a reason for hiding this comment

Uh oh!

mdonnalley Jun 11, 2021

Choose a reason for hiding this comment

Uh oh!

mdonnalley Jun 11, 2021

Choose a reason for hiding this comment

Uh oh!

mdonnalley left a comment

Choose a reason for hiding this comment

Uh oh!

amphro commented Jun 14, 2021

Uh oh!

RodEsp left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

RodEsp Jun 15, 2021

Choose a reason for hiding this comment

Uh oh!

RodEsp Jun 16, 2021

Choose a reason for hiding this comment

Uh oh!

RodEsp Jun 15, 2021 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RodEsp Jun 16, 2021

Choose a reason for hiding this comment

Uh oh!

RodEsp left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

RodEsp Jun 17, 2021

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

RodEsp Jun 15, 2021 •

edited

Loading

RodEsp left a comment •

edited

Loading