From be3b41acc61bacde9f4748decc205147e7aa5200 Mon Sep 17 00:00:00 2001 From: David Karlsson Date: Fri, 4 Nov 2022 19:47:00 +0100 Subject: [PATCH] docs: refactored file and directory structure Signed-off-by: David Karlsson --- README.md | 19 +++++++++++-------- bake/bake.go | 2 +- bake/compose.go | 2 +- commands/bake.go | 2 +- docs/manuals/README.md | 14 ++++++++++++++ .../bake/build-contexts.md | 0 docs/{guides => manuals}/bake/compose-file.md | 0 .../bake/configuring-build.md | 0 .../bake/file-definition.md | 0 docs/{guides => manuals}/bake/hcl-funcs.md | 0 docs/{guides => manuals}/bake/index.md | 0 .../cache/backends}/azblob.md | 0 .../cache => manuals/cache/backends}/gha.md | 0 .../cache => manuals/cache/backends}/index.md | 10 +++------- .../cache/backends}/inline.md | 0 .../cache => manuals/cache/backends}/local.md | 0 .../cache/backends}/registry.md | 0 .../cache => manuals/cache/backends}/s3.md | 0 .../drivers/docker-container.md | 2 +- docs/{guides => manuals}/drivers/docker.md | 0 docs/{guides => manuals}/drivers/index.md | 0 .../{guides => manuals}/drivers/kubernetes.md | 0 docs/{guides => manuals}/drivers/remote.md | 0 .../exporters/image-registry.md | 0 docs/{guides => manuals}/exporters/index.md | 5 +++-- .../exporters/local-tar.md | 0 .../exporters/oci-docker.md | 0 27 files changed, 35 insertions(+), 21 deletions(-) create mode 100644 docs/manuals/README.md rename docs/{guides => manuals}/bake/build-contexts.md (100%) rename docs/{guides => manuals}/bake/compose-file.md (100%) rename docs/{guides => manuals}/bake/configuring-build.md (100%) rename docs/{guides => manuals}/bake/file-definition.md (100%) rename docs/{guides => manuals}/bake/hcl-funcs.md (100%) rename docs/{guides => manuals}/bake/index.md (100%) rename docs/{guides/cache => manuals/cache/backends}/azblob.md (100%) rename docs/{guides/cache => manuals/cache/backends}/gha.md (100%) rename docs/{guides/cache => manuals/cache/backends}/index.md (94%) rename docs/{guides/cache => manuals/cache/backends}/inline.md (100%) rename docs/{guides/cache => manuals/cache/backends}/local.md (100%) rename docs/{guides/cache => manuals/cache/backends}/registry.md (100%) rename docs/{guides/cache => manuals/cache/backends}/s3.md (100%) rename docs/{guides => manuals}/drivers/docker-container.md (98%) rename docs/{guides => manuals}/drivers/docker.md (100%) rename docs/{guides => manuals}/drivers/index.md (100%) rename docs/{guides => manuals}/drivers/kubernetes.md (100%) rename docs/{guides => manuals}/drivers/remote.md (100%) rename docs/{guides => manuals}/exporters/image-registry.md (100%) rename docs/{guides => manuals}/exporters/index.md (98%) rename docs/{guides => manuals}/exporters/local-tar.md (100%) rename docs/{guides => manuals}/exporters/oci-docker.md (100%) diff --git a/README.md b/README.md index 882374fe..2fbe844d 100644 --- a/README.md +++ b/README.md @@ -32,15 +32,18 @@ Key features: - [Building with buildx](#building-with-buildx) - [Working with builder instances](#working-with-builder-instances) - [Building multi-platform images](#building-multi-platform-images) +- [Manuals](docs/manuals) + - [High-level build options with Bake](docs/manuals/bake/index.md) + - [Drivers](docs/manuals/drivers/index.md) + - [Exporters](docs/manuals/exporters/index.md) + - [Cache backends](docs/manuals/cache/backends/index.md) - [Guides](docs/guides) - - [High-level build options with Bake](docs/guides/bake/index.md) - [CI/CD](docs/guides/cicd.md) - [CNI networking](docs/guides/cni-networking.md) - [Using a custom network](docs/guides/custom-network.md) - [Using a custom registry configuration](docs/guides/custom-registry-config.md) - [OpenTelemetry support](docs/guides/opentelemetry.md) - [Registry mirror](docs/guides/registry-mirror.md) - - [Drivers](docs/guides/drivers/index.md) - [Resource limiting](docs/guides/resource-limiting.md) - [Reference](docs/reference/buildx.md) - [`buildx bake`](docs/reference/buildx_bake.md) @@ -191,12 +194,12 @@ through various "drivers". Each driver defines how and where a build should run, and have different feature sets. We currently support the following drivers: -- The `docker` driver ([guide](docs/guides/drivers/docker.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) -- The `docker-container` driver ([guide](docs/guides/drivers/docker-container.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) -- The `kubernetes` driver ([guide](docs/guides/drivers/kubernetes.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) -- The `remote` driver ([guide](docs/guides/drivers/remote.md)) +- The `docker` driver ([guide](docs/manuals/drivers/docker.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `docker-container` driver ([guide](docs/manuals/drivers/docker-container.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `kubernetes` driver ([guide](docs/manuals/drivers/kubernetes.md), [reference](https://docs.docker.com/engine/reference/commandline/buildx_create/#driver)) +- The `remote` driver ([guide](docs/manuals/drivers/remote.md)) -For more information on drivers, see the [drivers guide](docs/guides/drivers/index.md). +For more information on drivers, see the [drivers guide](docs/manuals/drivers/index.md). ## Working with builder instances @@ -313,7 +316,7 @@ cross-compilation helpers for more advanced use-cases. ## High-level build options -See [`docs/guides/bake/index.md`](docs/guides/bake/index.md) for more details. +See [`docs/manuals/bake/index.md`](docs/manuals/bake/index.md) for more details. # Contributing diff --git a/bake/bake.go b/bake/bake.go index 3df4844d..d4ca912a 100644 --- a/bake/bake.go +++ b/bake/bake.go @@ -569,7 +569,7 @@ type Target struct { NoCache *bool `json:"no-cache,omitempty" hcl:"no-cache,optional"` NetworkMode *string `json:"-" hcl:"-"` NoCacheFilter []string `json:"no-cache-filter,omitempty" hcl:"no-cache-filter,optional"` - // IMPORTANT: if you add more fields here, do not forget to update newOverrides and docs/guides/bake/file-definition.md. + // IMPORTANT: if you add more fields here, do not forget to update newOverrides and docs/manuals/bake/file-definition.md. // linked is a private field to mark a target used as a linked one linked bool diff --git a/bake/compose.go b/bake/compose.go index 2d500e3e..341f4e97 100644 --- a/bake/compose.go +++ b/bake/compose.go @@ -222,7 +222,7 @@ type xbake struct { NoCacheFilter stringArray `yaml:"no-cache-filter,omitempty"` Contexts stringMap `yaml:"contexts,omitempty"` // don't forget to update documentation if you add a new field: - // docs/guides/bake/compose-file.md#extension-field-with-x-bake + // docs/manuals/bake/compose-file.md#extension-field-with-x-bake } type stringMap map[string]string diff --git a/commands/bake.go b/commands/bake.go index 2fbb264f..ed6b28f0 100644 --- a/commands/bake.go +++ b/commands/bake.go @@ -112,7 +112,7 @@ func runBake(dockerCli command.Cli, targets []string, in bakeOptions) (err error tgts, grps, err := bake.ReadTargets(ctx, files, targets, overrides, map[string]string{ // don't forget to update documentation if you add a new - // built-in variable: docs/guides/bake/file-definition.md#built-in-variables + // built-in variable: docs/manuals/bake/file-definition.md#built-in-variables "BAKE_CMD_CONTEXT": cmdContext, "BAKE_LOCAL_PLATFORM": platforms.DefaultString(), }) diff --git a/docs/manuals/README.md b/docs/manuals/README.md new file mode 100644 index 00000000..7d7282a4 --- /dev/null +++ b/docs/manuals/README.md @@ -0,0 +1,14 @@ +# Buildx manuals 📚 + +This directory contains a bunch of useful docs for how to use Buildx features. + +> **Note** +> +> The markdown files in this directory (excluding this README) are reused +> downstream by the +> [Docker documentation repository](https://github.com/docker/docs). +> +> If you wish to contribute to these docs, be sure to first review the +> [documentation contribution guidelines](https://docs.docker.com/contribute/overview/). +> +> Thank you! diff --git a/docs/guides/bake/build-contexts.md b/docs/manuals/bake/build-contexts.md similarity index 100% rename from docs/guides/bake/build-contexts.md rename to docs/manuals/bake/build-contexts.md diff --git a/docs/guides/bake/compose-file.md b/docs/manuals/bake/compose-file.md similarity index 100% rename from docs/guides/bake/compose-file.md rename to docs/manuals/bake/compose-file.md diff --git a/docs/guides/bake/configuring-build.md b/docs/manuals/bake/configuring-build.md similarity index 100% rename from docs/guides/bake/configuring-build.md rename to docs/manuals/bake/configuring-build.md diff --git a/docs/guides/bake/file-definition.md b/docs/manuals/bake/file-definition.md similarity index 100% rename from docs/guides/bake/file-definition.md rename to docs/manuals/bake/file-definition.md diff --git a/docs/guides/bake/hcl-funcs.md b/docs/manuals/bake/hcl-funcs.md similarity index 100% rename from docs/guides/bake/hcl-funcs.md rename to docs/manuals/bake/hcl-funcs.md diff --git a/docs/guides/bake/index.md b/docs/manuals/bake/index.md similarity index 100% rename from docs/guides/bake/index.md rename to docs/manuals/bake/index.md diff --git a/docs/guides/cache/azblob.md b/docs/manuals/cache/backends/azblob.md similarity index 100% rename from docs/guides/cache/azblob.md rename to docs/manuals/cache/backends/azblob.md diff --git a/docs/guides/cache/gha.md b/docs/manuals/cache/backends/gha.md similarity index 100% rename from docs/guides/cache/gha.md rename to docs/manuals/cache/backends/gha.md diff --git a/docs/guides/cache/index.md b/docs/manuals/cache/backends/index.md similarity index 94% rename from docs/guides/cache/index.md rename to docs/manuals/cache/backends/index.md index 74031314..1fe6dc38 100644 --- a/docs/guides/cache/index.md +++ b/docs/manuals/cache/backends/index.md @@ -50,7 +50,7 @@ to import the cache from the storage backend into the current build. Unlike the local BuildKit cache (which is always enabled), all of the cache storage backends must be explicitly exported to, and explicitly imported from. All cache exporters except for the `inline` cache requires that you -[select an alternative Buildx driver](https://docs.docker.com/build/building/drivers/). +[select an alternative Buildx driver](../../drivers/index.md). Example `buildx` command using the `registry` backend, using import and export cache: @@ -127,10 +127,8 @@ with both parameters to find the results that work best for you. ### Cache compression - - The cache compression options are the same as the -[exporter compression options](https://docs.docker.com/build/building/exporters/#compression). +[exporter compression options](../../exporters/index.md#compression). For example, to compress the `registry` cache with `zstd` compression: @@ -142,10 +140,8 @@ $ docker buildx build --push -t / \ ### OCI media types - - The cache OCI options are the same as the -[exporter OCI options](https://docs.docker.com/build/building/exporters/#oci-media-types). +[exporter OCI options](../../exporters/index.md#oci-media-types). For example, to export OCI media type cache, use the `oci-mediatypes` property: diff --git a/docs/guides/cache/inline.md b/docs/manuals/cache/backends/inline.md similarity index 100% rename from docs/guides/cache/inline.md rename to docs/manuals/cache/backends/inline.md diff --git a/docs/guides/cache/local.md b/docs/manuals/cache/backends/local.md similarity index 100% rename from docs/guides/cache/local.md rename to docs/manuals/cache/backends/local.md diff --git a/docs/guides/cache/registry.md b/docs/manuals/cache/backends/registry.md similarity index 100% rename from docs/guides/cache/registry.md rename to docs/manuals/cache/backends/registry.md diff --git a/docs/guides/cache/s3.md b/docs/manuals/cache/backends/s3.md similarity index 100% rename from docs/guides/cache/s3.md rename to docs/manuals/cache/backends/s3.md diff --git a/docs/guides/drivers/docker-container.md b/docs/manuals/drivers/docker-container.md similarity index 98% rename from docs/guides/drivers/docker-container.md rename to docs/manuals/drivers/docker-container.md index 2c19292b..1ba2185d 100644 --- a/docs/guides/drivers/docker-container.md +++ b/docs/manuals/drivers/docker-container.md @@ -9,7 +9,7 @@ Docker driver. For example: - Specify custom BuildKit versions to use. - Build multi-arch images, see [QEMU](#qemu) - Advanced options for - [cache import and export](https://docs.docker.com/build/building/cache/) + [cache import and export](../cache/backends/index.md) ## Synopsis diff --git a/docs/guides/drivers/docker.md b/docs/manuals/drivers/docker.md similarity index 100% rename from docs/guides/drivers/docker.md rename to docs/manuals/drivers/docker.md diff --git a/docs/guides/drivers/index.md b/docs/manuals/drivers/index.md similarity index 100% rename from docs/guides/drivers/index.md rename to docs/manuals/drivers/index.md diff --git a/docs/guides/drivers/kubernetes.md b/docs/manuals/drivers/kubernetes.md similarity index 100% rename from docs/guides/drivers/kubernetes.md rename to docs/manuals/drivers/kubernetes.md diff --git a/docs/guides/drivers/remote.md b/docs/manuals/drivers/remote.md similarity index 100% rename from docs/guides/drivers/remote.md rename to docs/manuals/drivers/remote.md diff --git a/docs/guides/exporters/image-registry.md b/docs/manuals/exporters/image-registry.md similarity index 100% rename from docs/guides/exporters/image-registry.md rename to docs/manuals/exporters/image-registry.md diff --git a/docs/guides/exporters/index.md b/docs/manuals/exporters/index.md similarity index 98% rename from docs/guides/exporters/index.md rename to docs/manuals/exporters/index.md index caf9122c..71a5bae2 100644 --- a/docs/guides/exporters/index.md +++ b/docs/manuals/exporters/index.md @@ -144,8 +144,9 @@ $ docker buildx build --output type=tar,dest= . ``` The `local` exporter is useful in -[multi-stage builds](/build/building/multi-stage/) since it allows you to export -only a minimal number of build artifacts. For example, self-contained binaries. +[multi-stage builds](https://docs.docker.com/build/building/multi-stage/) since +it allows you to export only a minimal number of build artifacts. For example, +self-contained binaries. ### Cache-only export diff --git a/docs/guides/exporters/local-tar.md b/docs/manuals/exporters/local-tar.md similarity index 100% rename from docs/guides/exporters/local-tar.md rename to docs/manuals/exporters/local-tar.md diff --git a/docs/guides/exporters/oci-docker.md b/docs/manuals/exporters/oci-docker.md similarity index 100% rename from docs/guides/exporters/oci-docker.md rename to docs/manuals/exporters/oci-docker.md