[docs] move builders in to individual pages

docs/content/en/docs/pipeline-stages/builders/_index.md

@@ -0,0 +1,104 @@
+---
+title: "Build"
+linkTitle: "Build"
+weight: 10
+featureId: build
+---
+
+Skaffold has native support for several different tools for building images:
+
+* [Dockerfile]({{< relref "/docs/pipeline-stages/builders/docker" >}})
+  - locally with [Docker]({{< relref "/docs/pipeline-stages/builders/docker#dockerfile-locally" >}})
+  - in-cluster with [Kaniko]({{< relref "/docs/pipeline-stages/builders/docker#dockerfile-in-cluster-with-kaniko" >}})
+  - on cloud with [Google Cloud Build]({{< relref "/docs/pipeline-stages/builders/docker#dockerfile-remotely-with-google-cloud-build" >}})
+* [Jib Maven and Gradle]({{< relref "/docs/pipeline-stages/builders/jib" >}})
+  - [locally]({{< relref "/docs/pipeline-stages/builders/jib#jib-maven-and-gradle-locally" >}})
+  - on cloud with [Google Cloud Build]({{< relref "/docs/pipeline-stages/builders/jib#remotely-with-google-cloud-build" >}})
+* [Bazel]({{< relref "/docs/pipeline-stages/builders/bazel" >}}) locally
+* [Custom script] ({{< relref "/docs/pipeline-stages/builders/custom" >}})
+  - [locally]({{<relref "/docs/pipeline-stages/builders/custom#custom-build-script-locally" >}}) and
+  - [in cluster]({{<relref "/docs/pipeline-stages/builders/custom#custom-build-script-in-cluster" >}}) 
+* [CNCF Buildpacks] ({{< relref "/docs/pipeline-stages/builders/buildpacks" >}})
+
+The `build` section in the Skaffold configuration file, `skaffold.yaml`,
+controls how artifacts are built. To use a specific tool for building
+artifacts, add the value representing the tool and options for using that tool
+to the `build` section.
+
+For a detailed discussion on [Skaffold Configuration]({{< relref "/docs/design/config.md" >}}),
+see [skaffold.yaml References]({{< relref "/docs/references/yaml" >}}).
+
+
+Skaffold supports building artifacts in following execution contexts:
+
+1. Local
+2. In Cluster
+3. Remotely on Google Cloud Build.
+
+
+## Local Build
+Local build execution is the default execution context.
+Skaffold will use the build tools locally installed on your machine to execute the build.
+
+To configure the local execution explictly, add build type `local` to the build section of `skaffold.yaml`
+
+```yaml
+build:
+  local: {}
+```
+
+{{< schema root="LocalBuild" >}}
+
+If you are deploying to [local cluster]({{<relref "/docs/environment/local-cluster" >}}), you can additional set `push` to `false` to speed up builds.
+
+For building docker artifacts, you can specify 
+
+## In Cluster Build
+Skaffold supports building in cluster via [Kaniko]({{< relref "/docs/pipeline-stages/builders/docker#dockerfile-in-cluster-with-kaniko" >}}) 
+or [Custom Build Script]({{<relref "/docs/pipeline-stages/builders/custom#custom-build-script-in-cluster" >}}) 
+
+To configure in-cluster Build, add build type `cluster` to the build section of `skaffold.yaml`. 
+
+The following options can optionally be configured:
+
+{{< schema root="ClusterDetails" >}}
+
+## Remotely on Google Cloud Build
+
+Skaffold supports building remotely with Google Cloud Build.
+
+[Google Cloud Build](https://cloud.google.com/cloud-build/) is a
+[Google Cloud Platform](https://cloud.google.com) service that executes
+your builds using Google infrastructure. To get started with Google
+Build, see [Cloud Build Quickstart](https://cloud.google.com/cloud-build/docs/quickstart-docker).
+
+Skaffold can automatically connect to Cloud Build, and run your builds
+with it. After Cloud Build finishes building your artifacts, they will
+be saved to the specified remote registry, such as
+[Google Container Registry](https://cloud.google.com/container-registry/).
+
+Skaffold Google Cloud Build process differs from the gcloud command
+`gcloud builds submit`. Skaffold will create a list of dependent files
+and submit a tar file to GCB. It will then generate a single step `cloudbuild.yaml`
+and will start the building process. Skaffold does not honor `.gitignore` or `.gcloudignore`
+exclusions. If you need to ignore files use `.dockerignore`. Any `cloudbuild.yaml` found will not
+be used in the build process.
+
+**Configuration**
+
+To use Cloud Build, add build type `googleCloudBuild` to the `build`
+section of `skaffold.yaml`. The following options can optionally be configured:
+
+{{< schema root="GoogleCloudBuild" >}}
+
+
+Skaffold currently supports  [Docker]({{<relref "/docs/pipeline-stages/builders/docker#dockerfile-remotely-with-google-cloud-build">}})
+and [Jib]({{<relref "/docs/pipeline-stages/builders/jib#remotely-with-google-cloud-build">}}) Google Cloud Builders.
+
+
+
+
+
+
+
+

docs/content/en/docs/pipeline-stages/builders/bazel.md

@@ -0,0 +1,35 @@
+---
+title: "Bazel"
+linkTitle: "Bazel"
+weight: 30
+featureId: build
+---
+
+[Bazel](https://bazel.build/) is a fast, scalable, multi-language, and
+extensible build system.
+
+Skaffold can help build artifacts using Bazel locally; after Bazel finishes building
+container images, they will be loaded into the local Docker daemon.
+
+**Configuration**
+
+To use Bazel, `bazel` field to each artifact you specify in the
+`artifacts` part of the `build` section, and use the build type `local`.
+`context` should be a path containing the bazel files
+(`WORKSPACE` and `BUILD`). The following options can optionally be configured:
+
+{{< schema root="BazelArtifact" >}}
+
+{{% alert title="Not any Bazel target can be used" %}}
+The target specified must produce a bundle compatible
+with docker load. See
+<a href="https://github.com/bazelbuild/rules_docker#using-with-docker-locally">https://github.com/bazelbuild/rules_docker#using-with-docker-locally</a>
+{{% /alert %}}
+
+
+**Example**
+
+The following `build` section instructs Skaffold to build a
+Docker image `gcr.io/k8s-skaffold/example` with Bazel:
+
+{{% readfile file="samples/builders/bazel.yaml" %}}

docs/content/en/docs/pipeline-stages/builders/buildpacks.md

@@ -0,0 +1,8 @@
+---
+title: "CNCF Buildpacks"
+linkTitle: "Buildpacks"
+weight: 50
+featureId: build.buildpacks
+---
+
+[TODO #2904](https://github.com/GoogleContainerTools/skaffold/issues/2904)

docs/content/en/docs/pipeline-stages/builders/custom.md

@@ -0,0 +1,149 @@
+---
+title: "Custom Build Script"
+linkTitle: "Custom"
+weight: 40
+featureId: build.custom
+---
+
+Custom build scripts allow skaffold users the flexibility to build artifacts with any builder they desire. 
+Users can write a custom build script which must abide by the following contract for skaffold to work as expected:
+
+Currently, this only works with [local](#custom-build-script-locally) and 
+[cluster](#custom-build-script-in-cluster) build types. 
+### Contract between Skaffold and Custom Build Script
+
+Skaffold will pass in the following environment variables to the custom build script:
+
+| Environment Variable         | Description           | Expectation  |
+| ------------- |-------------| -----|
+| $IMAGE     | The fully qualified image name. For example, "gcr.io/image1:tag" | The custom build script is expected to build this image and tag it with the name provided in $IMAGE. The image should also be pushed if `$PUSH_IMAGE=true`. | 
+| $PUSH_IMAGE      | Set to true if the image in `$IMAGE` is expected to exist in a remote registry. Set to false if the image is expected to exist locally.      |   The custom build script will push the image `$IMAGE` if `$PUSH_IMAGE=true` | 
+| $BUILD_CONTEXT  | An absolute path to the directory this artifact is meant to be built from. Specified by artifact `context` in the skaffold.yaml.      | None. | 
+| Local environment variables | The current state of the local environment (e.g. `$HOST`, `$PATH)`. Determined by the golang [os.Environ](https://golang.org/pkg/os#Environ) function.| None. |
+
+As described above, the custom build script is expected to:
+
+1. Build and tag the `$IMAGE` image
+2. Push the image if `$PUSH_IMAGE=true`
+
+Once the build script has finished executing, skaffold will try to obtain the digest of the newly built image from a remote registry (if `$PUSH_IMAGE=true`) or the local daemon (if `$PUSH_IMAGE=false`).
+If skaffold fails to obtain the digest, it will error out.
+
+### Configuration
+
+To use a custom build script, add a `custom` field to each corresponding artifact in the `build` section of the skaffold.yaml.
+Supported schema for `custom` includes:
+
+{{< schema root="CustomArtifact" >}}
+
+`buildCommand` is *required* and points skaffold to the custom build script which will be executed to build the artifact.
+
+
+#### Custom Build Script Locally
+
+In addition to these [environment variables](#contract-between-skaffold-and-custom-build-script)
+Skaffold will pass in the following additional environment variables for local builder:
+
+| Environment Variable         | Description           | Expectation  |
+| ------------- |-------------| -----|
+| Docker daemon environment variables     | Inform the custom builder of which docker daemon endpoint we are using. Allows custom build scripts to work with tools like Minikube. For Minikube, this is the output of `minikube docker-env`.| None. | 
+
+**Configuration**
+
+To configure custom build script locally, in addition to adding a [`custom` field](#configuration) to each corresponding artifact in the `build`
+add `local` to you `build` config.
+
+#### Custom Build Script in Cluster
+
+In addition to these [environment variables](#contract-between-skaffold-and-custom-build-script)
+Skaffold will pass in the following additional environment variables for cluster builder:
+
+| Environment Variable         | Description           | Expectation  |
+| ------------- |-------------| -----|
+| $KUBECONTEXT    | The expected kubecontext in which the image will be built.| None. | 
+| $NAMESPACE      | The expected namespace in which the image will be built.| None. | 
+| $PULL_SECRET_NAME    | The name of the secret with authentication required to pull a base image/push the final image built on cluster.| None. | 
+| $DOCKER_CONFIG_SECRET_NAME    | The secret containing any required docker authentication for custom builds on cluster.| None. | 
+| $TIMEOUT        | The amount of time an on cluster build is allowed to run.| None. | 
+
+
+**Configuration**
+
+To configure custom build script locally, in addition to adding a [`custom` field](#configuration) to each corresponding artifact in the `build`
+add `cluster` to you `build` config.
+
+### Dependencies for a Custom Artifact
+
+`dependencies` tells the skaffold file watcher which files should be watched to trigger rebuilds and file syncs.  Supported schema for `dependencies` includes:
+
+{{< schema root="CustomDependencies" >}}
+
+#### Paths and Ignore
+
+`Paths` and `Ignore` are arrays used to list dependencies. 
+Any paths in `Ignore` will be ignored by the skaffold file watcher, even if they are also specified in `Paths`.
+`Ignore` will only work in conjunction with `Paths`, and with none of the other custom artifact dependency types.
+
+```yaml
+custom:
+  buildCommand: ./build.sh
+  dependencies:
+    paths:
+    - pkg/**
+    - src/*.go
+    ignore:
+    - vendor/**
+```
+
+#### Dockerfile
+
+Skaffold can calculate dependencies from a Dockerfile for a custom artifact.
+Passing in the path to the Dockerfile and any build args, if necessary, will allow skaffold to do dependency calculation.
+
+{{< schema root="DockerfileDependency" >}}
+
+```yaml
+custom:
+  buildCommand: ./build.sh
+  dependencies:
+    dockerfile:
+      path: path/to/Dockerfile
+      buildArgs:
+        file: foo
+```
+
+#### Getting dependencies from a command
+
+Sometimes you might have a builder that can provide the dependencies for a given artifact.
+For example bazel has the `bazel query deps` command.
+Custom artifact builders can ask Skaffold to execute a custom command, which Skaffold can use to get the dependencies for the artifact for file watching.
+
+The command *must* return dependencies as a JSON array, otherwise skaffold will error out.
+
+For example, the following configuration is valid, as executing the dependency command returns a valid JSON array.
+
+```yaml
+custom:
+  buildCommand: ./build.sh
+  dependencies:
+    command: echo ["file1","file2","file3"]
+```
+
+### Custom Build Scripts and File Sync
+
+Syncable files must be included in both the `paths` section of `dependencies`, so that the skaffold file watcher knows to watch them, and the `sync` section, so that skaffold knows to sync them.  
+
+### Custom Build Scripts and Logging
+
+`STDOUT` and `STDERR` from the custom build script will be redirected and displayed within skaffold logs.
+
+
+**Example**
+
+The following `build` section instructs Skaffold to build an image `gcr.io/k8s-skaffold/example` with a custom build script `build.sh`:
+
+{{% readfile file="samples/builders/custom.yaml" %}}
+
+A sample `build.sh` file, which builds an image with bazel and docker:
+
+{{% readfile file="samples/builders/build.sh" %}}