Merge pull request #1675 from dgageot/generate-skaffold-references

Generate skaffold references

Makefile

@@ -198,4 +198,4 @@ clean-docs-preview: docs-preview-image
 
 .PHONY: generate-schemas
 generate-schemas:
-	go run schemas/main.go
+	go run hack/schemas/main.go

deprecation-policy.md

@@ -21,7 +21,7 @@ A "deprecation event" would coincide with a release.
 a.) docs
 b.) release notes 
 c.) command help (if applicable)
-d.) annotated-skaffold.yaml (if applicable)
+d.) https://skaffold.dev/docs/references/yaml/ (if applicable)
 
 2. if applicable, [from the kubernetes policy](https://kubernetes.io/docs/reference/using-api/deprecation-policy/#deprecating-a-flag-or-cli): 
  > Rule #6: Deprecated CLI elements must emit warnings (optionally disable) when used.

docs/content/en/docs/concepts/_index.md

@@ -25,8 +25,7 @@ read the configuration file from the current directory.
 | `deploy` |  Specifies how Skaffold deploys artifacts. Skaffold supports using `kubectl`, `helm`, or `kustomize` to deploy artifacts. See [Deployers](/docs/how-tos/deployers) for more information. |
 | `profiles`|  Profile is a set of settings that, when activated, overrides the current configuration. You can use Profile to override the `build`, `test` and `deploy` sections. |
 
-You can learn more about the syntax of `skaffold.yaml` at
-[`skaffold.yaml References`](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/annotated-skaffold.yaml).
+You can [learn more](/docs/references/yaml) about the syntax of `skaffold.yaml`.
 
 ## Global configuration (~/.skaffold/config)
 

docs/content/en/docs/how-tos/builders/_index.md

@@ -21,7 +21,7 @@ controls how Skaffold builds artifacts. To use a specific tool for building
 artifacts, add the value representing the tool and options for using the tool
 to the `build` section. For a detailed discussion on Skaffold configuration,
 see [Skaffold Concepts: Configuration](/docs/concepts/#configuration) and
-[skaffold.yaml References](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/annotated-skaffold.yaml).
+[skaffold.yaml References](/docs/references/yaml).
 
 ## Dockerfile locally with Docker
 
@@ -42,11 +42,7 @@ of `skaffold.yaml`.
 
 The `local` type offers the following options:
 
-| Option        | Description | Default |
-|---------------|-------------|---------|
-| `push`        | Should images be pushed to a registry | `false` for local clusters, `true` for remote clusters. |
-| `useDockerCLI`| Uses `docker` command-line interface instead of Docker Engine APIs | `false` |
-| `useBuildkit` | Uses BuildKit to build Docker images | `false` |
+{{< schema root="LocalBuild" >}}
 
 The following `build` section, for example, instructs Skaffold to build a
 Docker image `gcr.io/k8s-skaffold/example` with the local Docker daemon: 
@@ -70,15 +66,7 @@ section of `skaffold.yaml`.
 
 The `googleCloudBuild` type offers the following options:
 
-| Option        | Description | Default |
-|---------------|-------------|---------|
-| `projectId`   | **Required** The ID of your Google Cloud Platform Project | |
-| `diskSizeGb`  | The disk size of the VM that runs the build. See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) for more information | |
-| `machineType` | The type of the VM that runs the build. See [Cloud Build API Reference: Build Options](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#buildoptions) for more information | |
-| `timeOut`     | The amount of time (in seconds) that this build should be allowed to run. See [Cloud Build API Reference: Resource/Build](https://cloud.google.com/cloud-build/docs/api/reference/rest/v1/projects.builds#resource-build) for more information. | |
-| `dockerImage` | The name of the image that will run a docker build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information | `gcr.io/cloud-builders/docker` |
-| `gradleImage` | The name of the image that will run a gradle build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information | `gcr.io/cloud-builders/gradle` |
-| `mavenImage`  | The name of the image that will run a maven build. See [Cloud builders](https://cloud.google.com/cloud-build/docs/cloud-builders) for more information | `gcr.io/cloud-builders/mvn` |
+{{< schema root="GoogleCloudBuild" >}}
 
 The following `build` section, for example, instructs Skaffold to build a
 Docker image `gcr.io/k8s-skaffold/example` with Google Cloud Build: 
@@ -99,13 +87,11 @@ To use Kaniko, add build type `kaniko` to the `build` section of
 
 The `kaniko` type offers the following options:
 
-| Option          | Description | Default |
-|-----------------|-------------|---------|
-| `buildContext`  | The Kaniko build context: `gcsBucket` or `localDir` | `localDir` |
-| `pullSecret`    | The path to the secret key file. See [Kaniko Documentation: Running Kaniko in a Kubernetes cluster](https://github.com/GoogleContainerTools/kaniko#running-kaniko-in-a-kubernetes-cluster) for more information | |
-| `pullSecretName`| The name of the Kubernetes secret for pulling the files from the build context and pushing the final image | `kaniko-secret` |
-| `namespace`     | The Kubernetes namespace | Current namespace in Kubernetes configuration |
-| `timeout`       | The amount of time (in seconds) that this build should be allowed to run | 20 minutes (`20m`) |
+{{< schema root="KanikoBuild" >}}
+
+The `buildContext` can be either:
+
+{{< schema root="KanikoBuildContext" >}}
 
 The following `build` section, for example, instructs Skaffold to build a
 Docker image `gcr.io/k8s-skaffold/example` with Kaniko: 
@@ -129,18 +115,11 @@ to use Jib already.
 
 The `jibMaven` type offers the following options:
 
-| Option          | Description | Default |
-|-----------------|-------------|---------|
-| `args`          | Additional command-line arguments for Maven | |
-| `profile`       | The Maven build profile to use | |
-| `module`        | The module to be built for a multi-module project; see below | |
+{{< schema root="JibMavenArtifact" >}}
 
 The `jibGradle` type offers the following options:
 
-| Option          | Description | Default |
-|-----------------|-------------|---------|
-| `args`          | Additional command-line arguments for Gradle | |
-| `project`       | The sub-project to be built for a multi-module project; see below | |
+{{< schema root="JibGradleArtifact" >}}
 
 See the [Skaffold-Jib demo project](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/jib/)
 for an example.
@@ -188,10 +167,7 @@ Bazel, `bazel` field to each artifact you specify in the
 
 The `bazel` type offers the following options:
 
-| Option    | Description |
-|-----------|-------------|
-| `target`  | **Required** The `bazel build` target to run |
-| `args`    | Additional args to pass to `bazel build` |
+{{< schema root="BazelArtifact" >}}
 
 The following `build` section, for example, instructs Skaffold to build a
 Docker image `gcr.io/k8s-skaffold/example` with Bazel:

docs/content/en/docs/how-tos/deployers/_index.md

@@ -24,7 +24,7 @@ controls how Skaffold builds artifacts. To use a specific tool for deploying
 artifacts, add the value representing the tool and options for using the tool
 to the `build` section. For a detailed discussion on Skaffold configuration,
 see [Skaffold Concepts: Configuration](/docs/concepts/#configuration) and
-[Skaffold.yaml References](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/annotated-skaffold.yaml).
+[Skaffold.yaml References](/docs/references/yaml).
 
 ## Deploying with kubectl
 
@@ -43,11 +43,11 @@ To use `kubectl`, add deploy type `kubectl` to the `deploy` section of
 
 The `kubectl` type offers the following options:
 
-| Option | Description | Default |
-|--------|-------------|---------|
-|`manifests`| A list of paths to Kubernetes Manifests | `k8s/*.yaml` |
-|`remoteManifests`| A list of paths to Kubernetes Manifests in remote clusters | |
-|`flags`| Additional flags to pass to `kubectl`. You can specify three types of flags: <ul> <li>`global`: flags that apply to every command.</li> <li>`apply`: flags that apply to creation commands.</li> <li>`delete`: flags that apply to deletion commands.</li><ul>| |
+{{< schema root="KubectlDeploy" >}}
+
+`flags` section offers the following options:
+
+{{< schema root="KubectlFlags" >}}
 
 The following `deploy` section, for example, instructs Skaffold to deploy
 artifacts using `kubectl`:
@@ -60,29 +60,15 @@ artifacts using `kubectl`:
 manage Kubernetes applications. Skaffold can work with Helm by calling its
 command-line interface.
 
-To use Helm with Skaffold, add deploy type `helm` to the `deploy` section
-of `skaffold.yaml`. The `helm` type offers the following options:
-
-| Option | Description |
-|--------|-------------|
-| `releases` | **Required** A list of Helm releases. See the table below for the schema of `releases`. |
-
-Each release includes the following fields:
-
-| Option | Description |
-|--------|-------------|
-|`name`| **Required** The name of the Helm release.|
-|`chartPath`| **Required** The path to the Helm chart.|
-|`valuesFilePath`| The path to the Helm `values` file.|
-|`values`| A list of key-value pairs supplementing the Helm `values` file.|
-|`namespace`| The Kubernetes namespace.|
-|`version`| The version of the chart.|
-|`setValues`| A list of key-value pairs; if present, Skaffold will sent `--set` flag to Helm CLI and append all pairs after the flag.|
-|`setValueTemplates`| A list of key-value pairs; if present, Skaffold will try to parse the value part of each key-value pair using environment variables in the system, then send `--set` flag to Helm CLI and append all parsed pairs after the flag.|
-|`wait`| A boolean value; if `true`, Skaffold will send `--wait` flag to Helm CLI.|
-|`recreatePods`| A boolean value; if `true`, Skaffold will send `--recreate-pods` flag to Helm CLI.|
-|`overrides`| A list of key-value pairs; if present, Skaffold will build a Helm `values` file that overrides the original and use it to call Helm CLI (`--f` flag).|
-|`packaged`|Packages the chart (`helm package`) Includes two fields: <ul> <li>`version`: Version of the chart.</li> <li>`appVersion`: Version of the app.</li> </ul>| |`imageStrategy`|Add image configurations to the Helm `values` file. Includes one of the two following fields: <ul> <li> `fqn`: The image configuration uses the syntax `IMAGE-NAME=IMAGE-REPOSITORY:IMAGE-TAG`. </li> <li>`helm`: The image configuration uses the syntax `IMAGE-NAME.repository=IMAGE-REPOSITORY, IMAGE-NAME.tag=IMAGE-TAG`.</li> </ul> |
+To use Helm with Skaffold, add deploy type `helm` to the `deploy` section of `skaffold.yaml`.
+
+The `helm` type offers the following options:
+
+{{< schema root="HelmDeploy" >}}
+
+Each `release` includes the following fields:
+
+{{< schema root="HelmRelease" >}}
 
 The following `deploy` section, for example, instructs Skaffold to deploy
 artifacts using `helm`:
@@ -96,12 +82,15 @@ developers to customize raw, template-free YAML files for multiple purposes.
 Skaffold can work with `kustomize` by calling its command-line interface.
 
 To use kustomize with Skaffold, add deploy type `kustomize` to the `deploy`
-section of `skaffold.yaml`. The `kustomize` type offers the following options:
+section of `skaffold.yaml`.
+
+The `kustomize` type offers the following options:
+
+{{< schema root="KustomizeDeploy" >}}
+
+`flags` section offers the following options:
 
-| Option | Description | Default |
-|--------|-------------|---------|
-|`path`| Path to Kustomization files | `.` (current directory) |
-|`flags`| Additional flags to pass to `kubectl`. You can specify three types of flags: <ul> <li>`global`: flags that apply to every command.</li> <li>`apply`: flags that apply to creation commands.</li> <li>`delete`: flags that apply to deletion commands.</li> <ul> | |
+{{< schema root="KubectlFlags" >}}
 
 The following `deploy` section, for example, instructs Skaffold to deploy
 artifacts using kustomize:

docs/content/en/docs/how-tos/profiles/_index.md

@@ -13,7 +13,7 @@ environments in your app's lifecycle, like Production or Development.
 You can create profiles in the `profiles` section of `skaffold.yaml`. For a
 detailed discussion on Skaffold configuration,
 see [Skaffold Concepts: Configuration](/docs/concepts/#configuration) and
-[skaffold.yaml References](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/annotated-skaffold.yaml).
+[skaffold.yaml References](/docs/references/yaml).
 
 ## Profiles (`profiles`)
 

docs/content/en/docs/how-tos/taggers/_index.md

@@ -17,7 +17,7 @@ Tag policy is specified in the `tagPolicy` field of the `build` section of the
 Skaffold configuration file, `skaffold.yaml`. For a detailed discussion on
 Skaffold configuration,
 see [Skaffold Concepts: Configuration](/docs/concepts/#configuration) and
-[skaffold.yaml References](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/annotated-skaffold.yaml).
+[skaffold.yaml References](/docs/references/yaml).
 
 ## `gitCommit`: using Git commit IDs as tags
 

docs/content/en/docs/references/_index.md

@@ -6,6 +6,6 @@ weight: 100
 
 | Skaffold References  |
 |----------|
-| [CLI References](/docs/references/cli) |
-| [skaffold.yaml References](https://github.com/GoogleContainerTools/skaffold/blob/master/examples/annotated-skaffold.yaml) |
+| [CLI](/docs/references/cli) |
+| [skaffold.yaml](/docs/references/yaml) |
 

docs/content/en/docs/references/cli/_index.md

@@ -1,6 +1,6 @@
 ---
-title: "CLI References"
-linkTitle: "CLI References"
+title: "CLI"
+linkTitle: "CLI"
 weight: 110
 ---
 

docs/content/en/docs/references/cli/index_header

@@ -1,6 +1,6 @@
 ---
-title: "CLI References"
-linkTitle: "CLI References"
+title: "CLI"
+linkTitle: "CLI"
 weight: 110
 ---
 

docs/content/en/docs/references/yaml/_index.html

@@ -0,0 +1,10 @@
+---
+title: "skaffold.yaml"
+linkTitle: "skaffold.yaml"
+weight: 120
+---
+
+<link href="https://fonts.googleapis.com/css?family=Roboto+Mono:400,700" rel="stylesheet">
+<link rel="stylesheet" type="text/css" href="main.css">
+<script type="module" src="main.js#{{% skaffold-version %}}"></script>
+<table id="table"></table>

schemas/main.css → docs/content/en/docs/references/yaml/main.css

@@ -19,8 +19,12 @@
     font-weight: 100;
 }
 
-.key, .value, .comment, .gray, .example {
+.key, .value, .comment, .example {
     font-family: 'Roboto Mono', monospace;
+    font-size: 14px;
+}
+
+.key, .value, .example {
     white-space: nowrap;
 }
 
@@ -30,7 +34,11 @@ table {
 
 td {
     border-bottom: 1px solid #EEE;
-    padding: 2px 0;
+    padding: 1px 0 !important;
+}
+
+td:first-child {
+    padding: 1px 5px !important;
 }
 
 td.top {
@@ -47,7 +55,7 @@ td:first-child {
 }
 
 tr:hover td {
-    background: #EEE;
+    background: #DDD;
 }
 
 code {