use custom annotation for aliases

Cobra allows for aliases to be defined for a command, but only allows these
to be defined at the same level (for example, `docker image ls` as alias for
`docker image list`). Our CLI has some commands that are available both as a
top-level shorthand as well as `docker <object> <verb>` subcommands. For example,
`docker ps` is a shorthand for `docker container ps` / `docker container ls`.

This patch introduces a custom "aliases" annotation that can be used to print
all available aliases for a command. While this requires these aliases to be
defined manually, in practice the list of aliases rarely changes, so maintenance
should be minimal.

As a convention, we could consider the first command in this list to be the
canonical command, so that we can use this information to add redirects in
our documentation in future.

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

clidocstool.go

@@ -18,6 +18,7 @@ import (
 	"errors"
 	"io"
 	"os"
+	"strings"
 
 	"github.com/spf13/cobra"
 )
@@ -99,6 +100,13 @@ func copyFile(src string, dst string) error {
 }
 
 func getAliases(cmd *cobra.Command) []string {
+	if a := cmd.Annotations["aliases"]; a != "" {
+		aliases := strings.Split(a, ",")
+		for i := 0; i < len(aliases); i++ {
+			aliases[i] = strings.TrimSpace(aliases[i])
+		}
+		return aliases
+	}
 	if len(cmd.Aliases) == 0 {
 		return cmd.Aliases
 	}

clidocstool_test.go

@@ -58,6 +58,9 @@ func init() {
 		Aliases: []string{"b"},
 		Short:   "Start a build",
 		Run:     func(cmd *cobra.Command, args []string) {},
+		Annotations: map[string]string{
+			"aliases": "docker image build, docker buildx build, docker buildx b, docker build",
+		},
 	}
 	buildxStopCmd = &cobra.Command{
 		Use:   "stop [NAME]",

fixtures/buildx_build.md

@@ -5,7 +5,7 @@ Start a build
 
 ### Aliases
 
-`docker buildx build`, `docker buildx b`
+`docker image build`, `docker buildx build`, `docker buildx b`, `docker build`
 
 ### Options
 

fixtures/docker_buildx_build.yaml

@@ -1,5 +1,5 @@
 command: docker buildx build
-aliases: docker buildx build, docker buildx b
+aliases: docker image build, docker buildx build, docker buildx b, docker build
 short: Start a build
 long: Start a build
 usage: docker buildx build [OPTIONS] PATH | URL | -