Skip to content

Add a way to add additional topics to generated usage texts #2323

@TLINDEN

Description

@TLINDEN

Checklist

  • Are you running the latest v3 release? The list of releases is here.
  • Did you check the manual for your release? The v3 manual is here.
  • Did you perform a search about this feature? Here's the GitHub guide about searching.

What problem does this solve?

I would like to be able to add additional topics to generated help messages.

Solution description

A good way would look something like this:

...
return &cli.Command{
  Name: "set",
  Topics: []cli.HelpTopics{
    &cli.HelpTopic{ // must be a map[string]string
      Reference: `https://example.com/api/overview`,
    }
  },
  ...

Which would generate:

NAME:
   esctl cluster settings set - set|update cluster settings

REFERENCE:
   https://example.com/api/overview

..

Describe alternatives you've considered

I am currently doing this:

	return &cli.Command{
		Name:      "set",
		Usage:     "set|update cluster settings",
		Aliases:   []string{"set", "update"},
		UsageText: "set [options] setting:value [setting:value ...]\nReference: " + SETTINGS,

		Flags: []cli.Flag{
			&cli.BoolFlag{
				Name:        "persistent",
				Usage:       "add persistent setting[s] (default)",
				Destination: &conf.Persistent,
				Aliases:     []string{"p"},
			},
			&cli.BoolFlag{
				Name:        "transient",
				Usage:       "add transient setting[s]",
				Destination: &conf.Transient,
				Aliases:     []string{"t"},
			},
		},

which outputs:

NAME:
   esctl cluster settings set - set|update cluster settings

USAGE:
   set [options] setting:value [setting:value ...]
   Reference: https://www.elastic.co/docs/reference/elasticsearch/configuration-reference

OPTIONS:
   --persistent, -p  add persistent setting[s] (default)
   --transient, -t   add transient setting[s]
   --help, -h        show help

So, the reference is just part of the usage. I could add it to the NAME topic, but this would be wrong as well.

Metadata

Metadata

Assignees

No one assigned

    Labels

    area/v3relates to / is being considered for v3status/triagemaintainers still need to look into this

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions