Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

display flag type and default value in a dedicated columns #19

Merged
merged 2 commits into from
Feb 23, 2022
Merged

display flag type and default value in a dedicated columns #19

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
8ced391
display flag type and default value in dedicated columns
crazy-max Feb 10, 2022
b3ecfe1
annotation to override default value
crazy-max Feb 17, 2022
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions annotation/annotation.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"
)
28 changes: 21 additions & 7 deletions clidocstool_md.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 {
Expand All @@ -193,19 +193,33 @@ 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 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 + "`"
}

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, "")
}
Expand Down
1 change: 1 addition & 0 deletions clidocstool_test.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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"`)

Expand Down
22 changes: 17 additions & 5 deletions clidocstool_yaml.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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], "`")
Expand Down
6 changes: 3 additions & 3 deletions fixtures/buildx.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |


<!---MARKER_GEN_END-->
Expand Down
48 changes: 24 additions & 24 deletions fixtures/buildx_build.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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\|<id>[=<socket>\|<key>[,<key>]]`) |
| [`-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` | 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`) |
| `--shm-size` | `string` | | Size of `/dev/shm` |
| `--ssh` | `stringArray` | | SSH agent socket or keys to expose to the build (format: `default\|<id>[=<socket>\|<key>[,<key>]]`) |
| [`-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 |


<!---MARKER_GEN_END-->
Expand Down
6 changes: 3 additions & 3 deletions fixtures/buildx_stop.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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 |


<!---MARKER_GEN_END-->
Expand Down
2 changes: 1 addition & 1 deletion fixtures/docker_buildx_build.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down