From 8ced39165e1cb118d6f9ce660f09430ac5bc928d Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Thu, 10 Feb 2022 14:48:35 +0100 Subject: [PATCH 1/2] display flag type and default value in dedicated columns Signed-off-by: CrazyMax --- clidocstool_md.go | 21 ++++++++++++------ fixtures/buildx.md | 6 ++--- fixtures/buildx_build.md | 48 ++++++++++++++++++++-------------------- fixtures/buildx_stop.md | 6 ++--- 4 files changed, 44 insertions(+), 37 deletions(-) diff --git a/clidocstool_md.go b/clidocstool_md.go index e08a76d..0f358b5 100644 --- a/clidocstool_md.go +++ b/clidocstool_md.go @@ -179,8 +179,8 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) { if cmd.Flags().HasAvailableFlags() { fmt.Fprint(b, "### Options\n\n") - fmt.Fprint(b, "| Name | Description |\n") - fmt.Fprint(b, "| --- | --- |\n") + fmt.Fprint(b, "| Name | Type | Default | Description |\n") + fmt.Fprint(b, "| --- | --- | --- | --- |\n") cmd.Flags().VisitAll(func(f *pflag.Flag) { if f.Hidden { @@ -193,19 +193,26 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) { name = mdMakeLink(name, f.Name, f, isLink) fmt.Fprintf(b, "%s, ", name) } - name := "`--" + f.Name + name := "`--" + f.Name + "`" + name = mdMakeLink(name, f.Name, f, isLink) + + var ftype string if f.Value.Type() != "bool" { - name += " " + f.Value.Type() + ftype = "`" + f.Value.Type() + "`" } - name += "`" - name = mdMakeLink(name, f.Name, f, isLink) + + var defval string + if f.DefValue != "" && (f.Value.Type() != "bool" && f.DefValue != "true") && f.DefValue != "[]" { + defval = "`" + f.DefValue + "`" + } + usage := f.Usage if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok { usage = strings.ReplaceAll(usage, cd[0], "`") } else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok { usage = strings.ReplaceAll(usage, cd, "`") } - fmt.Fprintf(b, "%s | %s |\n", mdEscapePipe(name), mdEscapePipe(usage)) + fmt.Fprintf(b, "%s | %s | %s | %s |\n", mdEscapePipe(name), mdEscapePipe(ftype), mdEscapePipe(defval), mdEscapePipe(usage)) }) fmt.Fprintln(b, "") } diff --git a/fixtures/buildx.md b/fixtures/buildx.md index 2dba8c8..a625820 100644 --- a/fixtures/buildx.md +++ b/fixtures/buildx.md @@ -13,9 +13,9 @@ Extended build capabilities with BuildKit ### Options -| Name | Description | -| --- | --- | -| `--builder string` | Override the configured builder instance | +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--builder` | `string` | | Override the configured builder instance | diff --git a/fixtures/buildx_build.md b/fixtures/buildx_build.md index 7c864cb..71a1a8b 100644 --- a/fixtures/buildx_build.md +++ b/fixtures/buildx_build.md @@ -9,30 +9,30 @@ Start a build ### Options -| Name | Description | -| --- | --- | -| [`--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 (format: `host:ip`) | -| `--allow stringSlice` | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | -| [`--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` | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | -| `--cache-to stringArray` | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) | -| [`--cgroup-parent string`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | Optional parent cgroup for the container | -| [`-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: `PATH/Dockerfile`) | -| `--iidfile string` | Write the image ID to the file | -| `--label stringArray` | Set metadata for an image | -| `--load` | Shorthand for `--output=type=docker` | -| `--network string` | Set the networking mode for the `RUN` instructions during build | -| `-o`, `--output stringArray` | Output destination (format: `type=local,dest=path`) | -| `--platform stringArray` | Set target platform for build | -| `--push` | Shorthand for `--output=type=registry` | -| `-q`, `--quiet` | Suppress the build output and print image ID on success | -| `--secret stringArray` | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) | -| `--shm-size string` | Size of `/dev/shm` | -| `--ssh stringArray` | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | -| [`-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 (format: `name:tag`) | -| [`--target string`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | Set the target build stage to build. | -| `--ulimit string` | Ulimit options | +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| [`--add-host`](https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host) | `stringSlice` | | Add a custom host-to-IP mapping (format: `host:ip`) | +| `--allow` | `stringSlice` | | Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) | +| [`--build-arg`](https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg) | `stringArray` | | Set build-time variables | +| `--builder` | `string` | | Override the configured builder instance | +| `--cache-from` | `stringArray` | | External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) | +| `--cache-to` | `stringArray` | | Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) | +| [`--cgroup-parent`](https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent) | `string` | | Optional parent cgroup for the container | +| [`-f`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f), [`--file`](https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f) | `string` | | Name of the Dockerfile (default: `PATH/Dockerfile`) | +| `--iidfile` | `string` | | Write the image ID to the file | +| `--label` | `stringArray` | | Set metadata for an image | +| `--load` | | | Shorthand for `--output=type=docker` | +| `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build | +| `-o`, `--output` | `stringArray` | | Output destination (format: `type=local,dest=path`) | +| `--platform` | `stringArray` | | Set target platform for build | +| `--push` | | | Shorthand for `--output=type=registry` | +| `-q`, `--quiet` | | | Suppress the build output and print image ID on success | +| `--secret` | `stringArray` | | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) | +| `--shm-size` | `string` | | Size of `/dev/shm` | +| `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|[=\|[,]]`) | +| [`-t`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t), [`--tag`](https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t) | `stringArray` | | Name and optionally a tag (format: `name:tag`) | +| [`--target`](https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target) | `string` | | Set the target build stage to build. | +| `--ulimit` | `string` | | Ulimit options | diff --git a/fixtures/buildx_stop.md b/fixtures/buildx_stop.md index 60097db..4eb7e67 100644 --- a/fixtures/buildx_stop.md +++ b/fixtures/buildx_stop.md @@ -5,9 +5,9 @@ Stop builder instance ### Options -| Name | Description | -| --- | --- | -| `--builder string` | Override the configured builder instance | +| Name | Type | Default | Description | +| --- | --- | --- | --- | +| `--builder` | `string` | | Override the configured builder instance | From b3ecfe17a17d969cdc8b244a8d1fb3e7261c26aa Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Thu, 17 Feb 2022 13:45:16 +0100 Subject: [PATCH 2/2] annotation to override default value Signed-off-by: CrazyMax --- annotation/annotation.go | 2 ++ clidocstool_md.go | 9 ++++++++- clidocstool_test.go | 1 + clidocstool_yaml.go | 22 +++++++++++++++++----- fixtures/buildx_build.md | 2 +- fixtures/docker_buildx_build.yaml | 2 +- 6 files changed, 30 insertions(+), 8 deletions(-) diff --git a/annotation/annotation.go b/annotation/annotation.go index 400bd9f..021846a 100644 --- a/annotation/annotation.go +++ b/annotation/annotation.go @@ -20,4 +20,6 @@ const ( // CodeDelimiter specifies the char that will be converted as code backtick. // Can be used on cmd for inheritance or a specific flag. CodeDelimiter = "docs.code-delimiter" + // DefaultValue specifies the default value for a flag. + DefaultValue = "docs.default-value" ) diff --git a/clidocstool_md.go b/clidocstool_md.go index 0f358b5..e58aada 100644 --- a/clidocstool_md.go +++ b/clidocstool_md.go @@ -202,7 +202,14 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) { } var defval string - if f.DefValue != "" && (f.Value.Type() != "bool" && f.DefValue != "true") && f.DefValue != "[]" { + if v, ok := f.Annotations[annotation.DefaultValue]; ok && len(v) > 0 { + defval = v[0] + if cd, ok := f.Annotations[annotation.CodeDelimiter]; ok { + defval = strings.ReplaceAll(defval, cd[0], "`") + } else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok { + defval = strings.ReplaceAll(defval, cd, "`") + } + } else if f.DefValue != "" && (f.Value.Type() != "bool" && f.DefValue != "true") && f.DefValue != "[]" { defval = "`" + f.DefValue + "`" } diff --git a/clidocstool_test.go b/clidocstool_test.go index 1f82925..36695f1 100644 --- a/clidocstool_test.go +++ b/clidocstool_test.go @@ -106,6 +106,7 @@ func init() { buildxBuildFlags.StringArrayP("output", "o", []string{}, `Output destination (format: "type=local,dest=path")`) buildxBuildFlags.StringArray("platform", []string{}, "Set target platform for build") + buildxBuildFlags.SetAnnotation("platform", annotation.DefaultValue, []string{"local"}) buildxBuildFlags.Bool("push", false, `Shorthand for "--output=type=registry"`) diff --git a/clidocstool_yaml.go b/clidocstool_yaml.go index 5af61ba..e945f9d 100644 --- a/clidocstool_yaml.go +++ b/clidocstool_yaml.go @@ -269,13 +269,25 @@ func genFlagResult(cmd *cobra.Command, flags *pflag.FlagSet, anchors map[string] flags.VisitAll(func(flag *pflag.Flag) { opt = cmdOption{ - Option: flag.Name, - ValueType: flag.Value.Type(), - DefaultValue: forceMultiLine(flag.DefValue, defaultValueMaxWidth), - Deprecated: len(flag.Deprecated) > 0, - Hidden: flag.Hidden, + Option: flag.Name, + ValueType: flag.Value.Type(), + Deprecated: len(flag.Deprecated) > 0, + Hidden: flag.Hidden, } + var defval string + if v, ok := flag.Annotations[annotation.DefaultValue]; ok && len(v) > 0 { + defval = v[0] + if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok { + defval = strings.ReplaceAll(defval, cd[0], "`") + } else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok { + defval = strings.ReplaceAll(defval, cd, "`") + } + } else { + defval = flag.DefValue + } + opt.DefaultValue = forceMultiLine(defval, defaultValueMaxWidth) + usage := flag.Usage if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok { usage = strings.ReplaceAll(usage, cd[0], "`") diff --git a/fixtures/buildx_build.md b/fixtures/buildx_build.md index 71a1a8b..9560363 100644 --- a/fixtures/buildx_build.md +++ b/fixtures/buildx_build.md @@ -24,7 +24,7 @@ Start a build | `--load` | | | Shorthand for `--output=type=docker` | | `--network` | `string` | `default` | Set the networking mode for the `RUN` instructions during build | | `-o`, `--output` | `stringArray` | | Output destination (format: `type=local,dest=path`) | -| `--platform` | `stringArray` | | Set target platform for build | +| `--platform` | `stringArray` | local | Set target platform for build | | `--push` | | | Shorthand for `--output=type=registry` | | `-q`, `--quiet` | | | Suppress the build output and print image ID on success | | `--secret` | `stringArray` | | Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) | diff --git a/fixtures/docker_buildx_build.yaml b/fixtures/docker_buildx_build.yaml index e32cf20..68cc04a 100644 --- a/fixtures/docker_buildx_build.yaml +++ b/fixtures/docker_buildx_build.yaml @@ -232,7 +232,7 @@ options: swarm: false - option: platform value_type: stringArray - default_value: '[]' + default_value: local description: Set target platform for build deprecated: false hidden: false