docs: standardize format for usage

Use the usage output of `--help` for each subcommand, to make
sure all flags/options are included on the page, and to make
it easier to keep docs in sync.

Note that the usage output is only used when reading these
docs on GitHub; docs.docker.com only consumes the "description"
and "example" sections (when present), and generates flag information
and usage output from source

Signed-off-by: Sebastiaan van Stijn <github@gone.nl>

docs/reference/buildx_bake.md

@@ -1,22 +1,24 @@
-# `buildx bake [OPTIONS] [TARGET...]`
+# buildx bake
 
-Bake is a high-level build command.
-
-Each specified target will run in parallel as part of the build.
+```
+Usage:  docker buildx bake [OPTIONS] [TARGET...]
 
-Options:
+Build from a file
 
-| Flag | Description |
-| --- | --- |
-|  -f, --file stringArray  | Build definition file
-|      --load              | Shorthand for --set=*.output=type=docker
-|      --no-cache          | Do not use cache when building the image
-|      --print             | Print the options without building
-|      --progress string   | Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto")
-|      --pull              | Always attempt to pull a newer version of the image
-|      --push              | Shorthand for --set=*.output=type=registry
-|      --set stringArray   | Override target value (eg: targetpattern.key=value)
+Aliases:
+  bake, f
 
+Options:
+      --builder string     Override the configured builder instance
+  -f, --file stringArray   Build definition file
+      --load               Shorthand for --set=*.output=type=docker
+      --no-cache           Do not use cache when building the image
+      --print              Print the options without building
+      --progress string    Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto")
+      --pull               Always attempt to pull a newer version of the image
+      --push               Shorthand for --set=*.output=type=registry
+      --set stringArray    Override target value (eg: targetpattern.key=value)
+```
 
 ## Description
 

docs/reference/buildx_build.md

@@ -1,32 +1,36 @@
-# `buildx build [OPTIONS] PATH | URL | -`
+# buildx build
 
-The `buildx build` command starts a build using BuildKit. This command is similar
-to the UI of `docker build` command and takes the same flags and arguments.
+```
+Usage:  docker buildx build [OPTIONS] PATH | URL | -
 
-Options:
+Start a build
 
-| Flag | Description |
-| --- | --- |
-| --add-host []         | Add a custom host-to-IP mapping (host:ip)
-| --allow []        | Allow extra privileged entitlement, e.g. network.host, security.insecure
-| --build-arg []    | Set build-time variables
-| --cache-from []   | External cache sources (eg. user/app:cache, type=local,src=path/to/dir)
-| --cache-to []     | Cache export destinations (eg. user/app:cache, type=local,dest=path/to/dir)
-| --file string              | Name of the Dockerfile (Default is 'PATH/Dockerfile')
-| --iidfile string           | Write the image ID to the file
-| --label []        | Set metadata for an image
-| --load                     | Shorthand for --output=type=docker
-| --network string           | Set the networking mode for the RUN instructions during build (default "default")
-| --no-cache                 | Do not use cache when building the image
-| --output []       | Output destination (format: type=local,dest=path)
-| --platform []     | Set target platform for build
-| --progress string          | Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto")
-| --pull                     | Always attempt to pull a newer version of the image
-| --push                     | Shorthand for --output=type=registry
-| --secret []       | Secret file to expose to the build: id=mysecret,src=/local/secret
-| --ssh []          | SSH agent socket or keys to expose to the build (format: default\|<id>[=<socket>\|<key>[,<key>]])
-| --tag []          | Name and optionally a tag in the 'name:tag' format
-| --target string            | Set the target build stage to build.
+Aliases:
+  build, b
+
+Options:
+      --add-host strings         Add a custom host-to-IP mapping (host:ip)
+      --allow strings            Allow extra privileged entitlement, e.g. network.host, security.insecure
+      --build-arg stringArray    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)
+  -f, --file string              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                     Shorthand for --output=type=docker
+      --network string           Set the networking mode for the RUN instructions during build (default "default")
+      --no-cache                 Do not use cache when building the image
+  -o, --output stringArray       Output destination (format: type=local,dest=path)
+      --platform stringArray     Set target platform for build
+      --progress string          Set type of progress output (auto, plain, tty). Use plain to show container output (default "auto")
+      --pull                     Always attempt to pull a newer version of the image
+      --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.
+```
 
 ## Description
 

docs/reference/buildx_create.md

@@ -1,19 +1,23 @@
-# `buildx create [OPTIONS] [CONTEXT|ENDPOINT]`
+# buildx create
 
-Options:
+```
+Usage:  docker buildx create [OPTIONS] [CONTEXT|ENDPOINT]
+
+Create a new builder instance
 
-| Flag | Description |
-| --- | --- |
-| --append                 | Append a node to builder instead of changing it
-| --buildkitd-flags string | Flags for buildkitd daemon
-| --config string          | BuildKit config file
-| --driver string          | Driver to use (eg. docker-container)
-| --driver-opt stringArray | Options for the driver
-| --leave                  | Remove a node from builder instead of changing it
-| --name string            | Builder instance name
-| --node string            | Create/modify node with given name
-| --platform stringArray   | Fixed platforms for current node
-| --use                    | Set the current builder instance
+Options:
+      --append                   Append a node to builder instead of changing it
+      --builder string           Override the configured builder instance
+      --buildkitd-flags string   Flags for buildkitd daemon
+      --config string            BuildKit config file
+      --driver string            Driver to use (available: [docker docker-container kubernetes])
+      --driver-opt stringArray   Options for the driver
+      --leave                    Remove a node from builder instead of changing it
+      --name string              Builder instance name
+      --node string              Create/modify node with given name
+      --platform stringArray     Fixed platforms for current node
+      --use                      Set the current builder instance
+```
 
 ## Description
 

docs/reference/buildx_imagetools_create.md

@@ -1,13 +1,17 @@
-# `buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]`
+# buildx imagetools create
 
-Options:
+```
+Usage:  docker buildx imagetools create [OPTIONS] [SOURCE] [SOURCE...]
+
+Create a new image based on source images
 
-| Flag | Description |
-| --- | --- |
-|      --append            | Append to existing manifest
-|      --dry-run           | Show final image instead of pushing
-|  -f, --file stringArray  | Read source descriptor from file
-|  -t, --tag stringArray   | Set reference for new image
+Options:
+      --append             Append to existing manifest
+      --builder string     Override the configured builder instance
+      --dry-run            Show final image instead of pushing
+  -f, --file stringArray   Read source descriptor from file
+  -t, --tag stringArray    Set reference for new image
+```
 
 ## Description
 

docs/reference/buildx_imagetools_inspect.md

@@ -1,4 +1,14 @@
-# `buildx imagetools inspect NAME`
+# buildx imagetools inspect
+
+```
+Usage:  docker buildx imagetools inspect [OPTIONS] NAME
+
+Show details of image in the registry
+
+Options:
+      --builder string   Override the configured builder instance
+      --raw              Show original JSON manifest
+```
 
 ## Description
 

docs/reference/buildx_inspect.md

@@ -1,4 +1,14 @@
-# `buildx inspect [NAME]`
+# buildx inspect
+
+```
+Usage:  docker buildx inspect [NAME]
+
+Inspect current builder instance
+
+Options:
+      --bootstrap        Ensure builder has booted before inspecting
+      --builder string   Override the configured builder instance
+```
 
 ## Description
 

docs/reference/buildx_ls.md

@@ -1,4 +1,13 @@
-# `buildx ls`
+# buildx ls
+
+```
+Usage:  docker buildx ls
+
+List builder instances
+
+Options:
+      --builder string   Override the configured builder instance
+```
 
 ## Description
 

docs/reference/buildx_rm.md

@@ -1,4 +1,13 @@
-# `buildx rm [NAME]`
+# buildx rm
+
+```
+Usage:  docker buildx rm [NAME]
+
+Remove a builder instance
+
+Options:
+      --builder string   Override the configured builder instance
+```
 
 ## Description
 

docs/reference/buildx_stop.md

@@ -1,4 +1,13 @@
-# `buildx stop [NAME]`
+# buildx stop
+
+```
+Usage:  docker buildx stop [NAME]
+
+Stop builder instance
+
+Options:
+      --builder string   Override the configured builder instance
+```
 
 ## Description
 

docs/reference/buildx_use.md

@@ -1,4 +1,15 @@
-# `buildx use NAME`
+# buildx use
+
+```
+Usage:  docker buildx use [OPTIONS] NAME
+
+Set the current builder instance
+
+Options:
+      --builder string   Override the configured builder instance
+      --default          Set builder as default for current context
+      --global           Builder persists context changes
+```
 
 ## Description