Generate Markdown docs (#414)

* Generate Markdown docs This is largely copied from similar work in go-containerregistry This required moving the Root command definition out of main() into a place where it could be referenced from the gendoc tooling. * fix boilerplate * moar fix boilerplate * update cmd/ko/main.go * set -j to GOMAXPROCS at runtime * rebase on cli-runtime change * remove trailing whitespace
ko-build · Aug 11, 2021 · 780c281 · 780c281
1 parent 86a7b6f
commit 780c281
Show file tree

Hide file tree

Showing 52 changed files with 10,556 additions and 100 deletions.
diff --git a/.github/workflows/verify.yaml b/.github/workflows/verify.yaml
@@ -5,55 +5,13 @@ on:
     branches: ['main']
 
 jobs:
-
   verify:
-    name: Verify Deps and Codegen
+    name: Verify Codegen
     runs-on: ubuntu-latest
-
-    env:
-      GOPATH: ${{ github.workspace }}
-
     steps:
     - uses: actions/setup-go@v2
       with:
         go-version: 1.16.x
-    - name: Check out code onto GOPATH
-      uses: actions/checkout@v2
-      with:
-        path: ./src/${{ github.event.repository.name }}
-
-    - name: Install Dependencies
-      run: |
-        go get github.com/google/go-licenses
-
-    - name: Update Codegen
-      shell: bash
-      run: |
-        pushd ./src/${{ github.event.repository.name }}
-        [[ ! -f hack/update-codegen.sh ]] || ./hack/update-codegen.sh
-        popd
-
+    - uses: actions/checkout@v2
     - name: Verify
-      shell: bash
-      run: |
-        # From: https://backreference.org/2009/12/23/how-to-match-newlines-in-sed/
-        # This is to leverage this workaround:
-        # https://github.com/actions/toolkit/issues/193#issuecomment-605394935
-        function urlencode() {
-          sed ':begin;$!N;s/\n/%0A/;tbegin'
-        }
-
-        pushd ./src/${{ github.event.repository.name }}
-        if [[ -z "$(git status --porcelain)" ]]; then
-            echo "${{ github.repository }} up to date."
-        else
-            # Print it both ways because sometimes we haven't modified the file (e.g. zz_generated),
-            # and sometimes we have (e.g. configmap checksum).
-            echo "Found diffs in: $(git diff-index --name-only HEAD --)"
-            for x in $(git diff-index --name-only HEAD --); do
-                echo "::error file=$x::Please run ./hack/update-codegen.sh.%0A$(git diff $x | urlencode)"
-            done
-            echo "${{ github.repository }} is out of date. Please run hack/update-codegen.sh"
-            exit 1
-        fi
-        popd
+      run: ./hack/presubmit.sh
diff --git a/cmd/help/main.go b/cmd/help/main.go
@@ -0,0 +1,45 @@
+// Copyright 2021 Google LLC All Rights Reserved.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//    http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"fmt"
+	"os"
+
+	"github.com/google/ko/pkg/commands"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+var dir string
+var root = &cobra.Command{
+	Use:   "gendoc",
+	Short: "Generate ko's help docs",
+	Args:  cobra.NoArgs,
+	RunE: func(*cobra.Command, []string) error {
+		return doc.GenMarkdownTree(commands.Root, dir)
+	},
+}
+
+func init() {
+	root.Flags().StringVarP(&dir, "dir", "d", ".", "Path to directory in which to generate docs")
+}
+
+func main() {
+	if err := root.Execute(); err != nil {
+		fmt.Println(err)
+		os.Exit(1)
+	}
+}
diff --git a/cmd/ko/main.go b/cmd/ko/main.go
@@ -24,9 +24,6 @@ import (
 
 	"github.com/google/go-containerregistry/pkg/logs"
 	"github.com/google/ko/pkg/commands"
-
-	cranecmd "github.com/google/go-containerregistry/cmd/crane/cmd"
-	"github.com/spf13/cobra"
 )
 
 const Deprecation258 = `NOTICE!
@@ -42,29 +39,9 @@ func main() {
 	logs.Warn.SetOutput(os.Stderr)
 	logs.Progress.SetOutput(os.Stderr)
 
-	// Parent command to which all subcommands are added.
-	cmds := &cobra.Command{
-		Use:   "ko",
-		Short: "Rapidly iterate with Go, Containers, and Kubernetes.",
-		Run: func(cmd *cobra.Command, args []string) {
-			cmd.Help()
-		},
-	}
-	commands.AddKubeCommands(cmds)
-
-	// Also add the auth group from crane to facilitate logging into a
-	// registry.
-	authCmd := cranecmd.NewCmdAuth("ko", "auth")
-	// That was a mistake, but just set it to Hidden so we don't break people.
-	authCmd.Hidden = true
-	cmds.AddCommand(authCmd)
-
-	// Just add a `ko login` command:
-	cmds.AddCommand(cranecmd.NewCmdAuthLogin())
-
 	log.Print(Deprecation258)
 
-	if err := cmds.Execute(); err != nil {
+	if err := commands.Root.Execute(); err != nil {
 		log.Fatalf("error during command execution: %v", err)
 	}
 }
diff --git a/doc/ko.md b/doc/ko.md
@@ -0,0 +1,28 @@
+## ko
+
+Rapidly iterate with Go, Containers, and Kubernetes.
+
+```
+ko [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for ko
+```
+
+### SEE ALSO
+
+* [ko apply](ko_apply.md)	 - Apply the input files with image references resolved to built/pushed image digests.
+* [ko completion](ko_completion.md)	 - Output shell completion code (default Bash)
+* [ko create](ko_create.md)	 - Create the input files with image references resolved to built/pushed image digests.
+* [ko delete](ko_delete.md)	 - See "kubectl help delete" for detailed usage.
+* [ko deps](ko_deps.md)	 - Print Go module dependency information about the ko-built binary in the image
+* [ko login](ko_login.md)	 - Log in to a registry
+* [ko publish](ko_publish.md)	 - Build and publish container images from the given importpaths.
+* [ko resolve](ko_resolve.md)	 - Print the input files with image references resolved to built/pushed image digests.
+* [ko run](ko_run.md)	 - A variant of `kubectl run` that containerizes IMPORTPATH first.
+* [ko version](ko_version.md)	 - Print ko version.
+
+###### Auto generated by spf13/cobra on 10-Aug-2021
diff --git a/doc/ko_apply.md b/doc/ko_apply.md
@@ -0,0 +1,91 @@
+## ko apply
+
+Apply the input files with image references resolved to built/pushed image digests.
+
+### Synopsis
+
+This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and then feeds the resulting yaml into "kubectl apply".
+
+```
+ko apply -f FILENAME [flags]
+```
+
+### Examples
+
+```
+
+  # Build and publish import path references to a Docker
+  # Registry as:
+  #   ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+  # Then, feed the resulting yaml into "kubectl apply".
+  # When KO_DOCKER_REPO is ko.local, it is the same as if
+  # --local was passed.
+  ko apply -f config/
+
+  # Build and publish import path references to a Docker
+  # Registry preserving import path names as:
+  #   ${KO_DOCKER_REPO}/<import path>
+  # Then, feed the resulting yaml into "kubectl apply".
+  ko apply --preserve-import-paths -f config/
+
+  # Build and publish import path references to a Docker
+  # daemon as:
+  #   ko.local/<import path>
+  # Then, feed the resulting yaml into "kubectl apply".
+  ko apply --local -f config/
+
+  # Apply from stdin:
+  cat config.yaml | ko apply -f -
+
+  # Any flags passed after '--' are passed to 'kubectl apply' directly:
+  ko apply -f config -- --namespace=foo --kubeconfig=cfg.yaml
+
+```
+
+### Options
+
+```
+      --as string                      Username to impersonate for the operation (DEPRECATED)
+      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups. (DEPRECATED)
+      --bare                           Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+  -B, --base-import-paths              Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+      --cache-dir string               Default cache directory (DEPRECATED)
+      --certificate-authority string   Path to a cert file for the certificate authority (DEPRECATED)
+      --client-certificate string      Path to a client certificate file for TLS (DEPRECATED)
+      --client-key string              Path to a client key file for TLS (DEPRECATED)
+      --cluster string                 The name of the kubeconfig cluster to use (DEPRECATED)
+      --context string                 The name of the kubeconfig context to use (DEPRECATED)
+      --disable-optimizations          Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+  -f, --filename strings               Filename, directory, or URL to files to use to create the resource
+  -h, --help                           help for apply
+      --image-label strings            Which labels (key=value) to add to the image.
+      --insecure-registry              Whether to skip TLS verification on the registry
+      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure (DEPRECATED)
+  -j, --jobs int                       The maximum number of concurrent builds (default GOMAXPROCS)
+      --kubeconfig string              Path to the kubeconfig file to use for CLI requests. (DEPRECATED)
+  -L, --local                          Load into images to local docker daemon.
+  -n, --namespace string               If present, the namespace scope for this CLI request (DEPRECATED)
+      --oci-layout-path string         Path to save the OCI image layout of the built images
+      --password string                Password for basic authentication to the API server (DEPRECATED)
+      --platform string                Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+  -P, --preserve-import-paths          Whether to preserve the full import path after KO_DOCKER_REPO.
+      --push                           Push images to KO_DOCKER_REPO (default true)
+  -R, --recursive                      Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
+      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (DEPRECATED)
+  -l, --selector string                Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)
+  -s, --server string                  The address and port of the Kubernetes API server (DEPRECATED)
+      --tag-only                       Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+  -t, --tags strings                   Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+      --tarball string                 File to save images tarballs
+      --tls-server-name string         Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used (DEPRECATED)
+      --token string                   Bearer token for authentication to the API server (DEPRECATED)
+      --user string                    The name of the kubeconfig user to use (DEPRECATED)
+      --username string                Username for basic authentication to the API server (DEPRECATED)
+  -W, --watch                          Continuously monitor the transitive dependencies of the passed yaml files, and redeploy whenever anything changes.
+```
+
+### SEE ALSO
+
+* [ko](ko.md)	 - Rapidly iterate with Go, Containers, and Kubernetes.
+
+###### Auto generated by spf13/cobra on 10-Aug-2021
diff --git a/doc/ko_completion.md b/doc/ko_completion.md
@@ -0,0 +1,20 @@
+## ko completion
+
+Output shell completion code (default Bash)
+
+```
+ko completion [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for completion
+      --zsh    Generates completion code for Zsh shell.
+```
+
+### SEE ALSO
+
+* [ko](ko.md)	 - Rapidly iterate with Go, Containers, and Kubernetes.
+
+###### Auto generated by spf13/cobra on 10-Aug-2021
diff --git a/doc/ko_create.md b/doc/ko_create.md
@@ -0,0 +1,91 @@
+## ko create
+
+Create the input files with image references resolved to built/pushed image digests.
+
+### Synopsis
+
+This sub-command finds import path references within the provided files, builds them into Go binaries, containerizes them, publishes them, and then feeds the resulting yaml into "kubectl create".
+
+```
+ko create -f FILENAME [flags]
+```
+
+### Examples
+
+```
+
+  # Build and publish import path references to a Docker
+  # Registry as:
+  #   ${KO_DOCKER_REPO}/<package name>-<hash of import path>
+  # Then, feed the resulting yaml into "kubectl create".
+  # When KO_DOCKER_REPO is ko.local, it is the same as if
+  # --local was passed.
+  ko create -f config/
+
+  # Build and publish import path references to a Docker
+  # Registry preserving import path names as:
+  #   ${KO_DOCKER_REPO}/<import path>
+  # Then, feed the resulting yaml into "kubectl create".
+  ko create --preserve-import-paths -f config/
+
+  # Build and publish import path references to a Docker
+  # daemon as:
+  #   ko.local/<import path>
+  # Then, feed the resulting yaml into "kubectl create".
+  ko create --local -f config/
+
+  # Create from stdin:
+  cat config.yaml | ko create -f -
+
+  # Any flags passed after '--' are passed to 'kubectl apply' directly:
+  ko apply -f config -- --namespace=foo --kubeconfig=cfg.yaml
+
+```
+
+### Options
+
+```
+      --as string                      Username to impersonate for the operation (DEPRECATED)
+      --as-group stringArray           Group to impersonate for the operation, this flag can be repeated to specify multiple groups. (DEPRECATED)
+      --bare                           Whether to just use KO_DOCKER_REPO without additional context (may not work properly with --tags).
+  -B, --base-import-paths              Whether to use the base path without MD5 hash after KO_DOCKER_REPO (may not work properly with --tags).
+      --cache-dir string               Default cache directory (DEPRECATED)
+      --certificate-authority string   Path to a cert file for the certificate authority (DEPRECATED)
+      --client-certificate string      Path to a client certificate file for TLS (DEPRECATED)
+      --client-key string              Path to a client key file for TLS (DEPRECATED)
+      --cluster string                 The name of the kubeconfig cluster to use (DEPRECATED)
+      --context string                 The name of the kubeconfig context to use (DEPRECATED)
+      --disable-optimizations          Disable optimizations when building Go code. Useful when you want to interactively debug the created container.
+  -f, --filename strings               Filename, directory, or URL to files to use to create the resource
+  -h, --help                           help for create
+      --image-label strings            Which labels (key=value) to add to the image.
+      --insecure-registry              Whether to skip TLS verification on the registry
+      --insecure-skip-tls-verify       If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure (DEPRECATED)
+  -j, --jobs int                       The maximum number of concurrent builds (default GOMAXPROCS)
+      --kubeconfig string              Path to the kubeconfig file to use for CLI requests. (DEPRECATED)
+  -L, --local                          Load into images to local docker daemon.
+  -n, --namespace string               If present, the namespace scope for this CLI request (DEPRECATED)
+      --oci-layout-path string         Path to save the OCI image layout of the built images
+      --password string                Password for basic authentication to the API server (DEPRECATED)
+      --platform string                Which platform to use when pulling a multi-platform base. Format: all | <os>[/<arch>[/<variant>]][,platform]*
+  -P, --preserve-import-paths          Whether to preserve the full import path after KO_DOCKER_REPO.
+      --push                           Push images to KO_DOCKER_REPO (default true)
+  -R, --recursive                      Process the directory used in -f, --filename recursively. Useful when you want to manage related manifests organized within the same directory.
+      --request-timeout string         The length of time to wait before giving up on a single server request. Non-zero values should contain a corresponding time unit (e.g. 1s, 2m, 3h). A value of zero means don't timeout requests. (DEPRECATED)
+  -l, --selector string                Selector (label query) to filter on, supports '=', '==', and '!='.(e.g. -l key1=value1,key2=value2)
+  -s, --server string                  The address and port of the Kubernetes API server (DEPRECATED)
+      --tag-only                       Include tags but not digests in resolved image references. Useful when digests are not preserved when images are repopulated.
+  -t, --tags strings                   Which tags to use for the produced image instead of the default 'latest' tag (may not work properly with --base-import-paths or --bare). (default [latest])
+      --tarball string                 File to save images tarballs
+      --tls-server-name string         Server name to use for server certificate validation. If it is not provided, the hostname used to contact the server is used (DEPRECATED)
+      --token string                   Bearer token for authentication to the API server (DEPRECATED)
+      --user string                    The name of the kubeconfig user to use (DEPRECATED)
+      --username string                Username for basic authentication to the API server (DEPRECATED)
+  -W, --watch                          Continuously monitor the transitive dependencies of the passed yaml files, and redeploy whenever anything changes.
+```
+
+### SEE ALSO
+
+* [ko](ko.md)	 - Rapidly iterate with Go, Containers, and Kubernetes.
+
+###### Auto generated by spf13/cobra on 10-Aug-2021
diff --git a/doc/ko_delete.md b/doc/ko_delete.md
@@ -0,0 +1,19 @@
+## ko delete
+
+See "kubectl help delete" for detailed usage.
+
+```
+ko delete [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for delete
+```
+
+### SEE ALSO
+
+* [ko](ko.md)	 - Rapidly iterate with Go, Containers, and Kubernetes.
+
+###### Auto generated by spf13/cobra on 10-Aug-2021