docs: add external docs links support

Signed-off-by: Tonis Tiigi <tonistiigi@gmail.com>

commands/build.go

@@ -238,8 +238,12 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
 	flags.BoolVar(&options.exportLoad, "load", false, "Shorthand for --output=type=docker")
 
 	flags.StringArrayVarP(&options.tags, "tag", "t", []string{}, "Name and optionally a tag in the 'name:tag' format")
+	flags.SetAnnotation("tag", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"})
 	flags.StringArrayVar(&options.buildArgs, "build-arg", []string{}, "Set build-time variables")
+	flags.SetAnnotation("build-arg", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"})
+
 	flags.StringVarP(&options.dockerfileName, "file", "f", "", "Name of the Dockerfile (Default is 'PATH/Dockerfile')")
+	flags.SetAnnotation("file", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"})
 
 	flags.StringArrayVar(&options.labels, "label", []string{}, "Set metadata for an image")
 
@@ -247,6 +251,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
 	flags.StringArrayVar(&options.cacheTo, "cache-to", []string{}, "Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)")
 
 	flags.StringVar(&options.target, "target", "", "Set the target build stage to build.")
+	flags.SetAnnotation("target", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"})
 
 	flags.StringSliceVar(&options.allow, "allow", []string{}, "Allow extra privileged entitlement, e.g. network.host, security.insecure")
 
@@ -254,6 +259,7 @@ func buildCmd(dockerCli command.Cli, rootOpts *rootOptions) *cobra.Command {
 	flags.BoolVarP(&options.quiet, "quiet", "q", false, "Suppress the build output and print image ID on success")
 	flags.StringVar(&options.networkMode, "network", "default", "Set the networking mode for the RUN instructions during build")
 	flags.StringSliceVar(&options.extraHosts, "add-host", []string{}, "Add a custom host-to-IP mapping (host:ip)")
+	flags.SetAnnotation("add-host", "docs.external.url", []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"})
 	flags.StringVar(&options.imageIDFile, "iidfile", "", "Write the image ID to the file")
 	flags.BoolVar(&options.squash, "squash", false, "Squash newly built layers into a single new layer")
 	flags.MarkHidden("quiet")

docs/docsgen/generate.go

@@ -90,8 +90,18 @@ func genCmd(cmd *cobra.Command, dir string) error {
 	return nil
 }
 
-func makeLink(txt, link string) string {
-	return "[" + txt + "](#" + link + ")"
+func makeLink(txt, link string, f *pflag.Flag, isAnchor bool) string {
+	link = "#" + link
+	annotations, ok := f.Annotations["docs.external.url"]
+	if ok && len(annotations) > 0 {
+		link = annotations[0]
+	} else {
+		if !isAnchor {
+			return txt
+		}
+	}
+
+	return "[" + txt + "](" + link + ")"
 }
 
 func cmdOutput(cmd *cobra.Command, old string) (string, error) {
@@ -140,9 +150,7 @@ func cmdOutput(cmd *cobra.Command, old string) (string, error) {
 			fmt.Fprint(b, "| ")
 			if f.Shorthand != "" {
 				name := "`-" + f.Shorthand + "`"
-				if isLink {
-					name = makeLink(name, f.Name)
-				}
+				name = makeLink(name, f.Name, f, isLink)
 				fmt.Fprintf(b, "%s, ", name)
 			}
 			name := "`--" + f.Name
@@ -150,9 +158,7 @@ func cmdOutput(cmd *cobra.Command, old string) (string, error) {
 				name += " " + f.Value.Type()
 			}
 			name += "`"
-			if isLink {
-				name = makeLink(name, f.Name)
-			}
+			name = makeLink(name, f.Name, f, isLink)
 			fmt.Fprintf(b, "%s | %s |\n", name, f.Usage)
 		})
 		fmt.Fprintln(b, "")

docs/reference/buildx_build.md

@@ -15,13 +15,13 @@ Start a build
 
 | Name | Description |
 | --- | --- |
-| `--add-host stringSlice` | Add a custom host-to-IP mapping (host:ip) |
+| [`--add-host stringSlice`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | Add a custom host-to-IP mapping (host:ip) |
 | [`--allow stringSlice`](#allow) | Allow extra privileged entitlement, e.g. network.host, security.insecure |
-| `--build-arg stringArray` | Set build-time variables |
+| [`--build-arg stringArray`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | Set build-time variables |
 | `--builder string` | Override the configured builder instance |
 | [`--cache-from stringArray`](#cache-from) | External cache sources (eg. user/app:cache, type=local,src=path/to/dir) |
 | [`--cache-to stringArray`](#cache-to) | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) |
-| `-f`, `--file string` | Name of the Dockerfile (Default is 'PATH/Dockerfile') |
+| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file string`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | Name of the Dockerfile (Default is 'PATH/Dockerfile') |
 | `--iidfile string` | Write the image ID to the file |
 | `--label stringArray` | Set metadata for an image |
 | [`--load`](#load) | Shorthand for --output=type=docker |
@@ -34,8 +34,8 @@ Start a build
 | [`--push`](#push) | Shorthand for --output=type=registry |
 | `--secret stringArray` | Secret file to expose to the build: id=mysecret,src=/local/secret |
 | `--ssh stringArray` | SSH agent socket or keys to expose to the build (format: default|<id>[=<socket>|<key>[,<key>]]) |
-| `-t`, `--tag stringArray` | Name and optionally a tag in the 'name:tag' format |
-| `--target string` | Set the target build stage to build. |
+| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag stringArray`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | Name and optionally a tag in the 'name:tag' format |
+| [`--target string`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | Set the target build stage to build. |
 
 
 <!---MARKER_GEN_END-->