From c712d9e5594a9c902a7077fa8fd4701814f7cac8 Mon Sep 17 00:00:00 2001 From: CrazyMax Date: Mon, 22 Nov 2021 10:33:16 +0100 Subject: [PATCH] annotation to specify code delimiter for flag usage Signed-off-by: CrazyMax --- annotation/annotation.go | 23 +++++ clidocstool.go | 5 -- clidocstool_md.go | 23 ++++- clidocstool_test.go | 129 +++++++++++++++++++------- clidocstool_yaml.go | 28 ++++-- example/main.go | 4 +- fixtures/buildx.md | 2 +- fixtures/buildx_build.md | 27 +++--- fixtures/docker_buildx.yaml | 4 +- fixtures/docker_buildx_build.yaml | 144 +++++++++++++++++++++++++++--- 10 files changed, 316 insertions(+), 73 deletions(-) create mode 100644 annotation/annotation.go diff --git a/annotation/annotation.go b/annotation/annotation.go new file mode 100644 index 0000000..400bd9f --- /dev/null +++ b/annotation/annotation.go @@ -0,0 +1,23 @@ +// Copyright 2021 cli-docs-tool authors +// +// Licensed under the Apache License, Version 2.0 (the "License"); +// you may not use this file except in compliance with the License. +// You may obtain a copy of the License at +// +// http://www.apache.org/licenses/LICENSE-2.0 +// +// Unless required by applicable law or agreed to in writing, software +// distributed under the License is distributed on an "AS IS" BASIS, +// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +// See the License for the specific language governing permissions and +// limitations under the License. + +package annotation + +const ( + // ExternalURL specifies an external link annotation + ExternalURL = "docs.external.url" + // 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" +) diff --git a/clidocstool.go b/clidocstool.go index 9dfb800..302fc59 100644 --- a/clidocstool.go +++ b/clidocstool.go @@ -22,11 +22,6 @@ import ( "github.com/spf13/cobra" ) -const ( - // AnnotationExternalUrl specifies an external link annotation - AnnotationExternalUrl = "docs.external.url" -) - // Options defines options for cli-docs-tool type Options struct { Root *cobra.Command diff --git a/clidocstool_md.go b/clidocstool_md.go index 7b1d6ec..e08a76d 100644 --- a/clidocstool_md.go +++ b/clidocstool_md.go @@ -24,6 +24,7 @@ import ( "strings" "text/template" + "github.com/docker/cli-docs-tool/annotation" "github.com/spf13/cobra" "github.com/spf13/pflag" ) @@ -51,6 +52,18 @@ func (c *Client) GenMarkdownTree(cmd *cobra.Command) error { sourcePath := filepath.Join(c.source, mdFile) targetPath := filepath.Join(c.target, mdFile) + // check recursively to handle inherited annotations + for curr := cmd; curr != nil; curr = curr.Parent() { + if _, ok := cmd.Annotations[annotation.CodeDelimiter]; !ok { + if cd, cok := curr.Annotations[annotation.CodeDelimiter]; cok { + if cmd.Annotations == nil { + cmd.Annotations = map[string]string{} + } + cmd.Annotations[annotation.CodeDelimiter] = cd + } + } + } + if !fileExists(sourcePath) { var icBuf bytes.Buffer icTpl, err := template.New("ic").Option("missingkey=error").Parse(`# {{ .Command }} @@ -120,7 +133,7 @@ func mdFilename(cmd *cobra.Command) string { func mdMakeLink(txt, link string, f *pflag.Flag, isAnchor bool) string { link = "#" + link - annotations, ok := f.Annotations[AnnotationExternalUrl] + annotations, ok := f.Annotations[annotation.ExternalURL] if ok && len(annotations) > 0 { link = annotations[0] } else { @@ -186,7 +199,13 @@ func mdCmdOutput(cmd *cobra.Command, old string) (string, error) { } name += "`" name = mdMakeLink(name, f.Name, f, isLink) - fmt.Fprintf(b, "%s | %s |\n", mdEscapePipe(name), mdEscapePipe(f.Usage)) + 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.Fprintln(b, "") } diff --git a/clidocstool_test.go b/clidocstool_test.go index d0440d4..1f82925 100644 --- a/clidocstool_test.go +++ b/clidocstool_test.go @@ -21,6 +21,7 @@ import ( "path/filepath" "testing" + "github.com/docker/cli-docs-tool/annotation" "github.com/spf13/cobra" "github.com/stretchr/testify/assert" "github.com/stretchr/testify/require" @@ -47,7 +48,11 @@ func init() { } buildxCmd = &cobra.Command{ Use: "buildx", - Short: "Build with BuildKit", + Short: "Docker Buildx", + Long: `Extended build capabilities with BuildKit`, + Annotations: map[string]string{ + annotation.CodeDelimiter: `"`, + }, } buildxBuildCmd = &cobra.Command{ Use: "build [OPTIONS] PATH | URL | -", @@ -65,39 +70,103 @@ func init() { buildxPFlags.String("builder", os.Getenv("BUILDX_BUILDER"), "Override the configured builder instance") buildxBuildFlags := buildxBuildCmd.Flags() - buildxBuildFlags.Bool("push", false, "Shorthand for --output=type=registry") - buildxBuildFlags.Bool("load", false, "Shorthand for --output=type=docker") - buildxBuildFlags.StringArrayP("tag", "t", []string{}, "Name and optionally a tag in the 'name:tag' format") - buildxBuildFlags.SetAnnotation("tag", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"}) + + var ignore string + var ignoreSlice []string + var ignoreBool bool + var ignoreInt int64 + + buildxBuildFlags.StringSlice("add-host", []string{}, `Add a custom host-to-IP mapping (format: 'host:ip')`) + buildxBuildFlags.SetAnnotation("add-host", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"}) + buildxBuildFlags.SetAnnotation("add-host", annotation.CodeDelimiter, []string{`'`}) + + buildxBuildFlags.StringSlice("allow", []string{}, `Allow extra privileged entitlement (e.g., "network.host", "security.insecure")`) + buildxBuildFlags.StringArray("build-arg", []string{}, "Set build-time variables") - buildxBuildFlags.SetAnnotation("build-arg", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"}) - buildxBuildFlags.StringP("file", "f", "", "Name of the Dockerfile (Default is 'PATH/Dockerfile')") - buildxBuildFlags.SetAnnotation("file", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"}) - buildxBuildFlags.StringArray("label", []string{}, "Set metadata for an image") - buildxBuildFlags.StringArray("cache-from", []string{}, "External cache sources (eg. user/app:cache, type=local,src=path/to/dir)") - buildxBuildFlags.StringArray("cache-to", []string{}, "Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)") - buildxBuildFlags.String("target", "", "Set the target build stage to build.") - buildxBuildFlags.SetAnnotation("target", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"}) - buildxBuildFlags.StringSlice("allow", []string{}, "Allow extra privileged entitlement, e.g. network.host, security.insecure") - buildxBuildFlags.StringArray("platform", []string{}, "Set target platform for build") - buildxBuildFlags.StringArray("secret", []string{}, "Secret file to expose to the build: id=mysecret,src=/local/secret") - buildxBuildFlags.StringArray("ssh", []string{}, "SSH agent socket or keys to expose to the build (format: `default|[=|[,]]`)") - buildxBuildFlags.StringArrayP("output", "o", []string{}, "Output destination (format: type=local,dest=path)") - // not implemented - buildxBuildFlags.String("network", "default", "Set the networking mode for the RUN instructions during build") - buildxBuildFlags.StringSlice("add-host", []string{}, "Add a custom host-to-IP mapping (host:ip)") - buildxBuildFlags.SetAnnotation("add-host", AnnotationExternalUrl, []string{"https://docs.docker.com/engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host"}) + buildxBuildFlags.SetAnnotation("build-arg", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#set-build-time-variables---build-arg"}) + + buildxBuildFlags.StringArray("cache-from", []string{}, `External cache sources (e.g., "user/app:cache", "type=local,src=path/to/dir")`) + + buildxBuildFlags.StringArray("cache-to", []string{}, `Cache export destinations (e.g., "user/app:cache", "type=local,dest=path/to/dir")`) + + buildxBuildFlags.String("cgroup-parent", "", "Optional parent cgroup for the container") + buildxBuildFlags.SetAnnotation("cgroup-parent", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent"}) + + buildxBuildFlags.StringP("file", "f", "", `Name of the Dockerfile (default: "PATH/Dockerfile")`) + buildxBuildFlags.SetAnnotation("file", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#specify-a-dockerfile--f"}) + buildxBuildFlags.String("iidfile", "", "Write the image ID to the file") - // hidden flags + + buildxBuildFlags.StringArray("label", []string{}, "Set metadata for an image") + + buildxBuildFlags.Bool("load", false, `Shorthand for "--output=type=docker"`) + + buildxBuildFlags.String("network", "default", `Set the networking mode for the "RUN" instructions during build`) + + buildxBuildFlags.StringArrayP("output", "o", []string{}, `Output destination (format: "type=local,dest=path")`) + + buildxBuildFlags.StringArray("platform", []string{}, "Set target platform for build") + + buildxBuildFlags.Bool("push", false, `Shorthand for "--output=type=registry"`) + buildxBuildFlags.BoolP("quiet", "q", false, "Suppress the build output and print image ID on success") - buildxBuildFlags.MarkHidden("quiet") - buildxBuildFlags.Bool("squash", false, "Squash newly built layers into a single new layer") - buildxBuildFlags.MarkHidden("squash") - buildxBuildFlags.String("ulimit", "", "Ulimit options") - buildxBuildFlags.MarkHidden("ulimit") - buildxBuildFlags.StringSlice("security-opt", []string{}, "Security options") + + buildxBuildFlags.StringArray("secret", []string{}, `Secret file to expose to the build (format: "id=mysecret,src=/local/secret")`) + + buildxBuildFlags.StringVar(&ignore, "shm-size", "", `Size of "/dev/shm"`) + + buildxBuildFlags.StringArray("ssh", []string{}, `SSH agent socket or keys to expose to the build (format: "default|[=|[,]]")`) + + buildxBuildFlags.StringArrayP("tag", "t", []string{}, `Name and optionally a tag (format: "name:tag")`) + buildxBuildFlags.SetAnnotation("tag", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#tag-an-image--t"}) + + buildxBuildFlags.String("target", "", "Set the target build stage to build.") + buildxBuildFlags.SetAnnotation("target", annotation.ExternalURL, []string{"https://docs.docker.com/engine/reference/commandline/build/#specifying-target-build-stage---target"}) + + buildxBuildFlags.StringVar(&ignore, "ulimit", "", "Ulimit options") + + // hidden flags + buildxBuildFlags.BoolVar(&ignoreBool, "compress", false, "Compress the build context using gzip") + buildxBuildFlags.MarkHidden("compress") + + buildxBuildFlags.StringVar(&ignore, "isolation", "", "Container isolation technology") + buildxBuildFlags.MarkHidden("isolation") + buildxBuildFlags.SetAnnotation("isolation", "flag-warn", []string{"isolation flag is deprecated with BuildKit."}) + + buildxBuildFlags.StringSliceVar(&ignoreSlice, "security-opt", []string{}, "Security options") buildxBuildFlags.MarkHidden("security-opt") - buildxBuildFlags.Bool("compress", false, "Compress the build context using gzip") + buildxBuildFlags.SetAnnotation("security-opt", "flag-warn", []string{`security-opt flag is deprecated. "RUN --security=insecure" should be used with BuildKit.`}) + + buildxBuildFlags.BoolVar(&ignoreBool, "squash", false, "Squash newly built layers into a single new layer") + buildxBuildFlags.MarkHidden("squash") + buildxBuildFlags.SetAnnotation("squash", "flag-warn", []string{"experimental flag squash is removed with BuildKit. You should squash inside build using a multi-stage Dockerfile for efficiency."}) + + buildxBuildFlags.StringVarP(&ignore, "memory", "m", "", "Memory limit") + buildxBuildFlags.MarkHidden("memory") + + buildxBuildFlags.StringVar(&ignore, "memory-swap", "", `Swap limit equal to memory plus swap: "-1" to enable unlimited swap`) + buildxBuildFlags.MarkHidden("memory-swap") + + buildxBuildFlags.Int64VarP(&ignoreInt, "cpu-shares", "c", 0, "CPU shares (relative weight)") + buildxBuildFlags.MarkHidden("cpu-shares") + + buildxBuildFlags.Int64Var(&ignoreInt, "cpu-period", 0, "Limit the CPU CFS (Completely Fair Scheduler) period") + buildxBuildFlags.MarkHidden("cpu-period") + + buildxBuildFlags.Int64Var(&ignoreInt, "cpu-quota", 0, "Limit the CPU CFS (Completely Fair Scheduler) quota") + buildxBuildFlags.MarkHidden("cpu-quota") + + buildxBuildFlags.StringVar(&ignore, "cpuset-cpus", "", `CPUs in which to allow execution ("0-3", "0,1")`) + buildxBuildFlags.MarkHidden("cpuset-cpus") + + buildxBuildFlags.StringVar(&ignore, "cpuset-mems", "", `MEMs in which to allow execution ("0-3", "0,1")`) + buildxBuildFlags.MarkHidden("cpuset-mems") + + buildxBuildFlags.BoolVar(&ignoreBool, "rm", true, "Remove intermediate containers after a successful build") + buildxBuildFlags.MarkHidden("rm") + + buildxBuildFlags.BoolVar(&ignoreBool, "force-rm", false, "Always remove intermediate containers") + buildxBuildFlags.MarkHidden("force-rm") buildxCmd.AddCommand(buildxBuildCmd) buildxCmd.AddCommand(buildxStopCmd) diff --git a/clidocstool_yaml.go b/clidocstool_yaml.go index 7dbcdff..55cd49d 100644 --- a/clidocstool_yaml.go +++ b/clidocstool_yaml.go @@ -24,6 +24,7 @@ import ( "sort" "strings" + "github.com/docker/cli-docs-tool/annotation" "github.com/spf13/cobra" "github.com/spf13/pflag" "gopkg.in/yaml.v2" @@ -165,7 +166,7 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error { cliDoc.Usage = cmd.UseLine() } - // Check recursively so that, e.g., `docker stack ls` returns the same output as `docker stack` + // check recursively to handle inherited annotations for curr := cmd; curr != nil; curr = curr.Parent() { if v, ok := curr.Annotations["version"]; ok && cliDoc.MinAPIVersion == "" { cliDoc.MinAPIVersion = v @@ -185,6 +186,14 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error { if o, ok := curr.Annotations["ostype"]; ok && cliDoc.OSType == "" { cliDoc.OSType = o } + if _, ok := cmd.Annotations[annotation.CodeDelimiter]; !ok { + if cd, cok := curr.Annotations[annotation.CodeDelimiter]; cok { + if cmd.Annotations == nil { + cmd.Annotations = map[string]string{} + } + cmd.Annotations[annotation.CodeDelimiter] = cd + } + } } anchors := make(map[string]struct{}) @@ -196,11 +205,11 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error { flags := cmd.NonInheritedFlags() if flags.HasFlags() { - cliDoc.Options = genFlagResult(flags, anchors) + cliDoc.Options = genFlagResult(cmd, flags, anchors) } flags = cmd.InheritedFlags() if flags.HasFlags() { - cliDoc.InheritedOptions = genFlagResult(flags, anchors) + cliDoc.InheritedOptions = genFlagResult(cmd, flags, anchors) } if hasSeeAlso(cmd) { @@ -238,7 +247,7 @@ func (c *Client) genYamlCustom(cmd *cobra.Command, w io.Writer) error { return nil } -func genFlagResult(flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOption { +func genFlagResult(cmd *cobra.Command, flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOption { var ( result []cmdOption opt cmdOption @@ -263,12 +272,19 @@ func genFlagResult(flags *pflag.FlagSet, anchors map[string]struct{}) []cmdOptio Option: flag.Name, ValueType: flag.Value.Type(), DefaultValue: forceMultiLine(flag.DefValue, defaultValueMaxWidth), - Description: forceMultiLine(flag.Usage, descriptionMaxWidth), Deprecated: len(flag.Deprecated) > 0, Hidden: flag.Hidden, } - if v, ok := flag.Annotations[AnnotationExternalUrl]; ok && len(v) > 0 { + usage := flag.Usage + if cd, ok := flag.Annotations[annotation.CodeDelimiter]; ok { + usage = strings.ReplaceAll(usage, cd[0], "`") + } else if cd, ok := cmd.Annotations[annotation.CodeDelimiter]; ok { + usage = strings.ReplaceAll(usage, cd, "`") + } + opt.Description = forceMultiLine(usage, descriptionMaxWidth) + + if v, ok := flag.Annotations[annotation.ExternalURL]; ok && len(v) > 0 { opt.DetailsURL = strings.TrimPrefix(v[0], "https://docs.docker.com") } else if _, ok = anchors[flag.Name]; ok { opt.DetailsURL = "#" + flag.Name diff --git a/example/main.go b/example/main.go index 0af4516..00c3b7a 100644 --- a/example/main.go +++ b/example/main.go @@ -46,8 +46,8 @@ func gen(opts *options) error { // root command cmd := &cobra.Command{ - Use: "buildx", - Short: "Build with BuildKit", + Use: "docker [OPTIONS] COMMAND [ARG...]", + Short: "The base command for the Docker CLI.", } // subcommand for the plugin diff --git a/fixtures/buildx.md b/fixtures/buildx.md index 1e07370..2dba8c8 100644 --- a/fixtures/buildx.md +++ b/fixtures/buildx.md @@ -1,7 +1,7 @@ # docker buildx -Build with BuildKit +Extended build capabilities with BuildKit ### Subcommands diff --git a/fixtures/buildx_build.md b/fixtures/buildx_build.md index 96df343..7c864cb 100644 --- a/fixtures/buildx_build.md +++ b/fixtures/buildx_build.md @@ -11,25 +11,28 @@ Start a build | 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 (host:ip) | -| `--allow stringSlice` | Allow extra privileged entitlement, e.g. network.host, security.insecure | +| [`--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 (eg. user/app:cache, type=local,src=path/to/dir) | -| `--cache-to stringArray` | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) | -| `--compress` | Compress the build context using gzip | -| [`-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') | +| `--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) | +| `--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 | -| `--secret stringArray` | Secret file to expose to the build: id=mysecret,src=/local/secret | +| `--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 in the 'name:tag' format | +| [`-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 | diff --git a/fixtures/docker_buildx.yaml b/fixtures/docker_buildx.yaml index 2481e95..c1e015f 100644 --- a/fixtures/docker_buildx.yaml +++ b/fixtures/docker_buildx.yaml @@ -1,6 +1,6 @@ command: docker buildx -short: Build with BuildKit -long: Build with BuildKit +short: Docker Buildx +long: Extended build capabilities with BuildKit pname: docker plink: docker.yaml cname: diff --git a/fixtures/docker_buildx_build.yaml b/fixtures/docker_buildx_build.yaml index 90fa350..e32cf20 100644 --- a/fixtures/docker_buildx_build.yaml +++ b/fixtures/docker_buildx_build.yaml @@ -9,7 +9,7 @@ options: - option: add-host value_type: stringSlice default_value: '[]' - description: Add a custom host-to-IP mapping (host:ip) + description: 'Add a custom host-to-IP mapping (format: `host:ip`)' details_url: /engine/reference/commandline/build/#add-entries-to-container-hosts-file---add-host deprecated: false hidden: false @@ -21,7 +21,7 @@ options: value_type: stringSlice default_value: '[]' description: | - Allow extra privileged entitlement, e.g. network.host, security.insecure + Allow extra privileged entitlement (e.g., `network.host`, `security.insecure`) deprecated: false hidden: false experimental: false @@ -43,7 +43,7 @@ options: value_type: stringArray default_value: '[]' description: | - External cache sources (eg. user/app:cache, type=local,src=path/to/dir) + External cache sources (e.g., `user/app:cache`, `type=local,src=path/to/dir`) deprecated: false hidden: false experimental: false @@ -54,7 +54,17 @@ options: value_type: stringArray default_value: '[]' description: | - Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir) + Cache export destinations (e.g., `user/app:cache`, `type=local,dest=path/to/dir`) + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cgroup-parent + value_type: string + description: Optional parent cgroup for the container + details_url: /engine/reference/commandline/build/#use-a-custom-parent-cgroup---cgroup-parent deprecated: false hidden: false experimental: false @@ -66,7 +76,56 @@ options: default_value: "false" description: Compress the build context using gzip deprecated: false - hidden: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpu-period + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) period + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpu-quota + value_type: int64 + default_value: "0" + description: Limit the CPU CFS (Completely Fair Scheduler) quota + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpu-shares + shorthand: c + value_type: int64 + default_value: "0" + description: CPU shares (relative weight) + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpuset-cpus + value_type: string + description: CPUs in which to allow execution (`0-3`, `0,1`) + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: cpuset-mems + value_type: string + description: MEMs in which to allow execution (`0-3`, `0,1`) + deprecated: false + hidden: true experimental: false experimentalcli: false kubernetes: false @@ -74,7 +133,7 @@ options: - option: file shorthand: f value_type: string - description: Name of the Dockerfile (Default is 'PATH/Dockerfile') + description: 'Name of the Dockerfile (default: `PATH/Dockerfile`)' details_url: /engine/reference/commandline/build/#specify-a-dockerfile--f deprecated: false hidden: false @@ -82,6 +141,16 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: force-rm + value_type: bool + default_value: "false" + description: Always remove intermediate containers + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: iidfile value_type: string description: Write the image ID to the file @@ -91,6 +160,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: isolation + value_type: string + description: Container isolation technology + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: label value_type: stringArray default_value: '[]' @@ -104,17 +182,37 @@ options: - option: load value_type: bool default_value: "false" - description: Shorthand for --output=type=docker + description: Shorthand for `--output=type=docker` deprecated: false hidden: false experimental: false experimentalcli: false kubernetes: false swarm: false +- option: memory + shorthand: m + value_type: string + description: Memory limit + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: memory-swap + value_type: string + description: | + Swap limit equal to memory plus swap: `-1` to enable unlimited swap + deprecated: false + hidden: true + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: network value_type: string default_value: default - description: Set the networking mode for the RUN instructions during build + description: Set the networking mode for the `RUN` instructions during build deprecated: false hidden: false experimental: false @@ -125,7 +223,7 @@ options: shorthand: o value_type: stringArray default_value: '[]' - description: 'Output destination (format: type=local,dest=path)' + description: 'Output destination (format: `type=local,dest=path`)' deprecated: false hidden: false experimental: false @@ -145,7 +243,7 @@ options: - option: push value_type: bool default_value: "false" - description: Shorthand for --output=type=registry + description: Shorthand for `--output=type=registry` deprecated: false hidden: false experimental: false @@ -158,6 +256,16 @@ options: default_value: "false" description: Suppress the build output and print image ID on success deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false +- option: rm + value_type: bool + default_value: "true" + description: Remove intermediate containers after a successful build + deprecated: false hidden: true experimental: false experimentalcli: false @@ -166,7 +274,8 @@ options: - option: secret value_type: stringArray default_value: '[]' - description: 'Secret file to expose to the build: id=mysecret,src=/local/secret' + description: | + Secret file to expose to the build (format: `id=mysecret,src=/local/secret`) deprecated: false hidden: false experimental: false @@ -183,6 +292,15 @@ options: experimentalcli: false kubernetes: false swarm: false +- option: shm-size + value_type: string + description: Size of `/dev/shm` + deprecated: false + hidden: false + experimental: false + experimentalcli: false + kubernetes: false + swarm: false - option: squash value_type: bool default_value: "false" @@ -208,7 +326,7 @@ options: shorthand: t value_type: stringArray default_value: '[]' - description: Name and optionally a tag in the 'name:tag' format + description: 'Name and optionally a tag (format: `name:tag`)' details_url: /engine/reference/commandline/build/#tag-an-image--t deprecated: false hidden: false @@ -230,7 +348,7 @@ options: value_type: string description: Ulimit options deprecated: false - hidden: true + hidden: false experimental: false experimentalcli: false kubernetes: false