docs: use "examples" section, and rephrase headings

Put the flag descriptions/examples under an "examples"
section (used at docs.docker.com), and rephrase the
headings to be more consistent with other pages in the
docker documentation.

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

docs/reference/buildx_bake.md

@@ -25,12 +25,12 @@ Options:
 Bake is a high-level build command. Each specified target will run in parallel
 as part of the build.
 
+## Examples
 
-### `-f, --file FILE`
+### Specify a build definition file (-f, --file)
 
-Specifies the bake definition file. The file can be a Docker Compose, JSON or HCL
+By default, `buildx bake` looks for build definition files in the current directory,
-file. If multiple files are specified they are all read and configurations are
+the following are parsed:
-combined. By default, if no files are specified, the following are parsed:
 
 - `docker-compose.yml`
 - `docker-compose.yaml`
@@ -39,11 +39,48 @@ combined. By default, if no files are specified, the following are parsed:
 - `docker-bake.hcl`
 - `docker-bake.override.hcl`
 
-### `--no-cache`
+Use the `-f` / `--file` option to specify the build definition file to use. The
+file can be a Docker Compose, JSON or HCL file. If multiple files are specified
+they are all read and configurations are combined.
+
+The following example uses a Docker Compose file named `docker-compose.dev.yaml`
+as build definition file, and builds all targets in the file:
+
+```console
+$ docker buildx bake -f docker-compose.dev.yaml
+
+[+] Building 66.3s (30/30) FINISHED
+ => [frontend internal] load build definition from Dockerfile  0.1s
+ => => transferring dockerfile: 36B                            0.0s
+ => [backend internal] load build definition from Dockerfile   0.2s
+ => => transferring dockerfile: 3.73kB                         0.0s
+ => [database internal] load build definition from Dockerfile  0.1s
+ => => transferring dockerfile: 5.77kB                         0.0s
+ ...
+```
+
+Pass the names of the targets to build, to build only specific target(s). The
+following example builds the `backend` and `database` targets that are defined
+in the `docker-compose.dev.yaml` file, skipping the build for the `frontend`
+target:
+
+```console
+$ docker buildx bake -f docker-compose.dev.yaml backend database
+
+[+] Building 2.4s (13/13) FINISHED
+ => [backend internal] load build definition from Dockerfile  0.1s
+ => => transferring dockerfile: 81B                           0.0s
+ => [database internal] load build definition from Dockerfile 0.2s
+ => => transferring dockerfile: 36B                           0.0s
+ => [backend internal] load .dockerignore                     0.3s
+ ...
+```
+
+### Do not use cache when building the image (--no-cache)
 
 Same as `build --no-cache`. Do not use cache when building the image.
 
-### `--print`
+### Print the options without building (--print)
 
 Prints the resulting options of the targets desired to be built, in a JSON format,
 without starting a build.
@@ -63,16 +100,37 @@ $ docker buildx bake -f docker-bake.hcl --print db
 }
 ```
 
-### `--progress`
+### Set type of progress output (--progress)
 
 Same as `build --progress`. Set type of progress output (auto, plain, tty). Use
 plain to show container output (default "auto").
 
-### `--pull`
+The following example uses `plain` output during the build:
+
+```console
+$ docker buildx bake --progress=plain
+
+#2 [backend internal] load build definition from Dockerfile.test
+#2 sha256:de70cb0bb6ed8044f7b9b1b53b67f624e2ccfb93d96bb48b70c1fba562489618
+#2 ...
+
+#1 [database internal] load build definition from Dockerfile.test
+#1 sha256:453cb50abd941762900a1212657a35fc4aad107f5d180b0ee9d93d6b74481bce
+#1 transferring dockerfile: 36B done
+#1 DONE 0.1s
+...
+```
+
+
+### Always attempt to pull a newer version of the image (--pull)
 
 Same as `build --pull`.
 
-### `--set targetpattern.key[.subkey]=value`
+### Override target configurations from command line (--set)
+
+```
+--set targetpattern.key[.subkey]=value
+```
 
 Override target configurations from command line. The pattern matching syntax is
 defined in https://golang.org/pkg/path/#Match.

docs/reference/buildx_build.md

@@ -41,7 +41,13 @@ For documentation on most of these flags refer to the [`docker build`
 documentation](https://docs.docker.com/engine/reference/commandline/build/). In
 here we’ll document a subset of the new flags.
 
-### `--platform=value[,value]`
+## Examples
+
+### Set the target platforms for the build (--platform)
+
+```
+--platform=value[,value]
+```
 
 Set the target platform for the build. All `FROM` commands inside the Dockerfile
 without their own `--platform` flag will pull base images for this platform and
@@ -78,7 +84,11 @@ docker buildx build --platform=linux/amd64,linux/arm64,linux/arm/v7 .
 docker buildx build --platform=darwin .
 ```
 
-### `-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]`
+### Set the export action for the build result (-o, --output)
+
+```
+-o, --output=[PATH,-,type=TYPE[,KEY=VALUE]
+```
 
 Sets the export action for the build result. In `docker build` all builds finish
 by creating a container image and exporting it to `docker images`. `buildx` makes
@@ -166,17 +176,21 @@ Attribute keys:
 The `registry` exporter is a shortcut for `type=image,push=true`.
 
 
-### `--push`
+### Push the build result to a registry (--push)
 
 Shorthand for [`--output=type=registry`](#registry). Will automatically push the
 build result to registry.
 
-### `--load`
+### Load the single-platform build result to `docker images` (--load)
 
 Shorthand for [`--output=type=docker`](#docker). Will automatically load the
 single-platform build result to `docker images`.
 
-### `--cache-from=[NAME|type=TYPE[,KEY=VALUE]]`
+### Use an external cache source for a build (--cache-from)
+
+```
+--cache-from=[NAME|type=TYPE[,KEY=VALUE]]
+```
 
 Use an external cache source for a build. Supported types are `registry` and `local`.
 The `registry` source can import cache from a cache manifest or (special) image
@@ -196,7 +210,11 @@ docker buildx build --cache-from=type=registry,ref=user/app .
 docker buildx build --cache-from=type=local,src=path/to/cache .
 ```
 
-### `--cache-to=[NAME|type=TYPE[,KEY=VALUE]]`
+### Export build cache to an external cache destination (--cache-to)
+
+```
+--cache-to=[NAME|type=TYPE[,KEY=VALUE]]
+```
 
 Export build cache to an external cache destination. Supported types are `registry`,
 `local` and `inline`. Registry exports build cache to a cache manifest in the
@@ -222,7 +240,11 @@ docker buildx build --cache-to=type=registry,ref=user/app .
 docker buildx build --cache-to=type=local,dest=path/to/cache .
 ```
 
-### `--allow=ENTITLEMENT`
+### Allow extra privileged entitlement (--allow)
+
+```console
+--allow=ENTITLEMENT
+```
 
 Allow extra privileged entitlement. List of entitlements:
 

docs/reference/buildx_create.md

@@ -31,11 +31,13 @@ context/endpoint value.
 Builder instances are isolated environments where builds can be invoked. All
 docker contexts also get the default builder instance.
 
-### `--append`
+## Examples
 
-Changes the action of the command to appends a new node to an existing builder
+### Append a new node to an existing builder (--append)
-specified by `--name`. Buildx will choose an appropriate node for a build based
+
-on the platforms it supports.
+The `--append` flag changes the action of the command to append a new node to an
+existing builder specified by `--name`. Buildx will choose an appropriate node
+for a build based on the platforms it supports.
 
 Example:
 
@@ -47,7 +49,11 @@ $ docker buildx create --name eager_beaver --append mycontext2
 eager_beaver
 ```
 
-### `--buildkitd-flags FLAGS`
+### Specify options for the buildkitd daemon (--buildkitd-flags)
+
+```
+--buildkitd-flags FLAGS
+```
 
 Adds flags when starting the buildkitd daemon. They take precedence over the
 configuration file specified by [`--config`](#--config-file). See `buildkitd --help`
@@ -59,13 +65,21 @@ Example:
 --buildkitd-flags '--debug --debugaddr 0.0.0.0:6666'
 ```
 
-### `--config FILE`
+### Specify a configuration file for the buildkitd daemon (--config)
+
+```
+--config FILE
+```
 
 Specifies the configuration file for the buildkitd daemon to use. The configuration
 can be overridden by [`--buildkitd-flags`](#--buildkitd-flags-flags).
 See an [example buildkitd configuration file](https://github.com/moby/buildkit/blob/master/docs/buildkitd.toml.md).
 
-### `--driver DRIVER`
+### Set the builder driver to use (--driver)
+
+```
+--driver DRIVER
+```
 
 Sets the builder driver to be used. There are two available drivers, each have
 their own specificities.
@@ -82,7 +96,11 @@ their own specificities.
   with defined buildkit container image to build your images.
 
 
-### `--driver-opt OPTIONS`
+### Set additional driver-specific options (--driver-opt)
+
+```
+--driver-opt OPTIONS
+```
 
 Passes additional driver-specific options. Details for each driver:
 
@@ -103,10 +121,11 @@ Passes additional driver-specific options. Details for each driver:
     - `rootless=(true|false)` - Run the container as a non-root user without `securityContext.privileged`. [Using Ubuntu host kernel is recommended](https://github.com/moby/buildkit/blob/master/docs/rootless.md). Defaults to false.
     - `loadbalance=(sticky|random)` - Load-balancing strategy. If set to "sticky", the pod is chosen using the hash of the context path. Defaults to "sticky"
 
-### `--leave`
+### Remove a node from a builder (--leave)
 
-Changes the action of the command to removes a node from a builder. The builder
+The `--leave` flag changes the action of the command to remove a node from a
-needs to be specified with `--name` and node that is removed is set with `--node`.
+builder. The builder needs to be specified with `--name` and node that is removed
+is set with `--node`.
 
 Example:
 
@@ -114,23 +133,36 @@ Example:
 docker buildx create --name mybuilder --node mybuilder0 --leave
 ```
 
-### `--name NAME`
+### Specify the name of the builder (--name)
 
-Specifies the name of the builder to be created or modified. If none is specified,
+```
-one will be automatically generated.
+--name NAME
+```
 
-### `--node NODE`
+The `--name` flag specifies the name of the builder to be created or modified.
+If none is specified, one will be automatically generated.
 
-Specifies the name of the node to be created or modified. If none is specified,
+### Specify the name of the node (--node)
-it is the name of the builder it belongs to, with an index number suffix.
 
-### `--platform PLATFORMS`
+```
+--node NODE
+```
+
+The `--node` flag specifies the name of the node to be created or modified. If
+none is specified, it is the name of the builder it belongs to, with an index
+number suffix.
+
+### Set the platforms supported by the node
+
+```
+--platform PLATFORMS
+```
 
-Sets the platforms supported by the node. It expects a comma-separated list of
+The `--platform` flag sets the platforms supported by the node. It expects a
-platforms of the form OS/architecture/variant. The node will also automatically
+comma-separated list of platforms of the form OS/architecture/variant. The node
-detect the platforms it supports, but manual values take priority over the
+will also automatically detect the platforms it supports, but manual values take
-detected ones and can be used when multiple nodes support building for the same
+priority over the detected ones and can be used when multiple nodes support
-platform.
+building for the same platform.
 
 Example:
 
@@ -139,7 +171,7 @@ docker buildx create --platform linux/amd64
 docker buildx create --platform linux/arm64,linux/arm/v8
 ```
 
-### `--use`
+### Automatically switch to the newly created builder
 
-Automatically switches the current builder to the newly created one. Equivalent
+The `--use` flag automatically switches the current builder to the newly created
-to running `docker buildx use $(docker buildx create ...)`.
+one. Equivalent to running `docker buildx use $(docker buildx create ...)`.

docs/reference/buildx_imagetools_create.md

@@ -23,22 +23,33 @@ manifests can be manifest lists or single platform distribution manifests and
 must already exist in the registry where the new manifest is created. If only
 one source is specified create performs a carbon copy.
 
-### `--append`
+## Examples
 
-Append appends the new sources to an existing manifest list in the destination.
+### Append new sources to an existing manifest list (--append)
 
-### `--dry-run`
+Use the `--append` flag to append the new sources to an existing manifest list
+in the destination.
 
-Do not push the image, just show it.
+### Show final image instead of pushing (--dry-run)
 
-### `-f, --file FILE`
+Use the `--dry-run` flag to not push the image, just show it.
+
+### Read source descriptor from a file (-f, --file)
+
+```
+-f FILE or --file FILE
+```
 
 Reads source from files. A source can be a manifest digest, manifest reference,
 or a JSON of OCI descriptor object.
 
-### `-t, --tag IMAGE`
+### Set reference for new image  (-t, --tag)
+
+```
+-t IMAGE or --tag IMAGE
+```
 
-Name of the image to be created.
+Use the `-t` or `--tag` flag to set the name of the image to be created.
 
 Examples:
 

docs/reference/buildx_inspect.md

@@ -14,7 +14,14 @@ Options:
 
 Shows information about the current or specified builder.
 
-Example:
+## Examples
+
+### Get information about a builder instance
+
+By default, `inspect` shows information about the current builder. Specify the
+name of the builder to inspect to get information about that builder.
+The following example shows information about a builder instance named
+`elated_tesla`:
 
 ```console
 $ docker buildx inspect elated_tesla
@@ -34,10 +41,11 @@ Status:    running
 Platforms: linux/arm64, linux/arm/v7, linux/arm/v6
 ```
 
-### `--bootstrap`
+### Ensure that the builder is running before inspecting (--bootstrap)
 
-Ensures that the builder is running before inspecting it. If the driver is
+Use the `--bootstrap` option to ensures that the builder is running before
-`docker-container`, then `--bootstrap` starts the buildkit container and waits
+inspecting it. If the driver is `docker-container`, then `--bootstrap` starts
-until it is operational. Bootstrapping is automatically done during build, it is
+the buildkit container and waits until it is operational. Bootstrapping is
-thus not necessary. The same BuildKit container is used during the lifetime of
+automatically done during build, it is thus not necessary. The same BuildKit
-the associated builder node (as displayed in `buildx ls`).
+container is used during the lifetime of the associated builder node (as
+displayed in `buildx ls`).