From 4047bccf6cb8f4505f0cbfeccb4601203cf69428 Mon Sep 17 00:00:00 2001 From: Tonis Tiigi Date: Tue, 23 Mar 2021 11:07:57 -0700 Subject: [PATCH] docs: add external docs links support Signed-off-by: Tonis Tiigi --- commands/build.go | 6 ++++++ docs/docsgen/generate.go | 22 ++++++++++++++-------- docs/reference/buildx_build.md | 10 +++++----- 3 files changed, 25 insertions(+), 13 deletions(-) diff --git a/commands/build.go b/commands/build.go index 9a470d17..d1d66308 100644 --- a/commands/build.go +++ b/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") diff --git a/docs/docsgen/generate.go b/docs/docsgen/generate.go index eb09c076..e6e98e9f 100644 --- a/docs/docsgen/generate.go +++ b/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, "") diff --git a/docs/reference/buildx_build.md b/docs/reference/buildx_build.md index 60d96ac7..aef600c7 100644 --- a/docs/reference/buildx_build.md +++ 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|[=|[,]]) | -| `-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. |