Tidy up cli docs for public release (#50)

Signed-off-by: Liam White <liam@tetrate.io>

go.sum

@@ -74,6 +74,7 @@ github.com/coreos/go-semver v0.3.0/go.mod h1:nnelYz7RCh+5ahJtPPxZlU+153eP4D4r3Ee
 github.com/coreos/go-systemd v0.0.0-20181031085051-9002847aa142/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
 github.com/coreos/pkg v0.0.0-20180928190104-399ea9e2e55f/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
 github.com/coreos/prometheus-operator v0.29.0/go.mod h1:SO+r5yZUacDFPKHfPoUjI3hMsH+ZUdiuNNhuSq3WoSg=
+github.com/cpuguy83/go-md2man v1.0.10 h1:BSKMNlYxDvnunlTymqtgONjNnaRV1sTpcovwwjF22jk=
 github.com/cpuguy83/go-md2man v1.0.10/go.mod h1:SmD6nW6nTyfqj6ABTjUi3V3JVMnlJmwcJI5acqYI6dE=
 github.com/cyphar/filepath-securejoin v0.2.2/go.mod h1:FpkQEhXnPnOthhzymB7CGsFk2G9VLXONKD9G7QGMM+4=
 github.com/d4l3k/messagediff v1.2.1 h1:ZcAIMYsUg0EAp9X+tt8/enBE/Q8Yd5kzPynLyKptt9U=
@@ -391,6 +392,7 @@ github.com/prometheus/prom2json v1.2.1/go.mod h1:yIcXOj/TLPdtZ12qRyhswPnu+02sfDo
 github.com/rcrowley/go-metrics v0.0.0-20181016184325-3113b8401b8a/go.mod h1:bCqnVzQkZxMG4s8nGwiZ5l3QUCyqpo9Y+/ZMZ9VjZe4=
 github.com/rogpeppe/fastuuid v0.0.0-20150106093220-6724a57986af/go.mod h1:XWv6SoW27p1b0cqNHllgS5HIMJraePCO15w5zCzIWYg=
 github.com/rogpeppe/go-charset v0.0.0-20180617210344-2471d30d28b4/go.mod h1:qgYeAmZ5ZIpBWTGllZSQnw97Dj+woV0toclVaRGI8pc=
+github.com/russross/blackfriday v1.5.2 h1:HyvC0ARfnZBqnXwABFeSZHpKvJHJJfPz81GNueLj0oo=
 github.com/russross/blackfriday v1.5.2/go.mod h1:JO/DiYxRf+HjHt06OyowR9PTA263kcR/rfWxYHBV53g=
 github.com/ryanuber/go-glob v0.0.0-20160226084822-572520ed46db/go.mod h1:807d1WSdnB0XRJzKNil9Om6lcp/3a0v4qIHxIXzX/Yc=
 github.com/satori/go.uuid v1.2.0/go.mod h1:dA0hQrYB0VpLJoorglMZABFdXlWrHn1NEOzdhQKdks0=

pkg/cmd/doc.go

@@ -0,0 +1,63 @@
+// Copyright 2019 Tetrate
+//
+// 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 cmd
+
+import (
+	"fmt"
+	"path"
+	"path/filepath"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+var (
+	outputDir string
+	linkDir   string
+)
+
+// NewDocCmd returns command that generates documentation
+func NewDocCmd() *cobra.Command {
+	cmd := &cobra.Command{
+		Use:    "doc",
+		Short:  "Generates markdown documentation for the cli.",
+		Hidden: true,
+		RunE: func(cmd *cobra.Command, _ []string) error {
+			getenvoy := cmd.Parent()
+			return doc.GenMarkdownTreeCustom(getenvoy, outputDir, filePrepender, linkHandler)
+		},
+	}
+	cmd.PersistentFlags().StringVarP(&outputDir, "output", "o", "", "directory to create generated docs")
+	cmd.PersistentFlags().StringVarP(&linkDir, "link", "l", "", "directory to prepend to filename in links")
+	return cmd
+}
+
+func filePrepender(filename string) string {
+	name := filepath.Base(filename)
+	base := strings.TrimSuffix(name, path.Ext(name))
+	return fmt.Sprintf(fmTemplate, strings.ReplaceAll(base, "_", " "))
+}
+
+const fmTemplate = `+++
+title = "%s"
+type = "docs"
++++
+`
+
+func linkHandler(name string) string {
+	base := strings.TrimSuffix(name, path.Ext(name))
+	return filepath.Join(linkDir, strings.ToLower(base))
+}

pkg/cmd/fetch.go

@@ -25,16 +25,16 @@ import (
 // NewFetchCmd create a command responsible for retrieving Envoy binaries
 func NewFetchCmd() *cobra.Command {
 	return &cobra.Command{
-		Use:   "fetch [binary]",
-		Short: "Retreives the passed Envoy binary.",
+		Use:   "fetch <reference>",
+		Short: "Retrieve Envoy binaries from GetEnvoy.",
 		Long: `
-Retreives the passed Envoy binary. 
-Location can be a full or partial manifest reference, use getenvoy list for a complete list of available builds.`,
-		Example: `# Fetch using a partial manifest reference to retrieve a build for your operating system.
+Retrieves the referenced Envoy binary from GetEnvoy. The reference can be a full or partial reference.
+A complete list of available builds can be retrieved using` + "`getenvoy list`" + `.`,
+		Example: `# Fetch using a partial manifest reference to retrieve a build suitable for your operating system.
 getenvoy fetch standard:1.11.1
 		
-# Fetch using a full manifest reference to retrieve a specific build. 
-getenvoy fetch standard:1.11.1/debian`,
+# Fetch using a full manifest reference to retrieve a specific build for Linux. 
+getenvoy fetch standard:1.11.1/linux-glibc`,
 		Args: func(cmd *cobra.Command, args []string) error {
 			if len(args) == 0 {
 				return errors.New("missing binary parameter")

pkg/cmd/list.go

@@ -25,7 +25,9 @@ import (
 func NewListCmd() *cobra.Command {
 	return &cobra.Command{
 		Use:   "list",
-		Short: "Lists available Envoys from GetEnvoy.",
+		Short: "List available Envoys provided by GetEnvoy.",
+		Long: `
+Retrieves a list of Envoy builds provided by GetEnvoy.`,
 		RunE: func(cmd *cobra.Command, _ []string) error {
 			return manifest.Print(os.Stdout, manifestURL)
 		},

pkg/cmd/root.go

@@ -22,24 +22,22 @@ import (
 // NewRoot create a new root command and sets the cliVersion to the passed variable
 // TODO: Add version support on the command
 func NewRoot() *cobra.Command {
-	runCmd := NewRunCmd()
-	rootCmd.AddCommand(runCmd)
+	rootCmd.AddCommand(NewRunCmd())
+	rootCmd.AddCommand(NewListCmd())
+	rootCmd.AddCommand(NewFetchCmd())
+	rootCmd.AddCommand(NewDocCmd())
 
-	listCmd := NewListCmd()
-	rootCmd.AddCommand(listCmd)
-
-	fetchCmd := NewFetchCmd()
-	rootCmd.AddCommand(fetchCmd)
-
-	rootCmd.PersistentFlags().StringVarP(&manifestURL, "url", "u", manifest.DefaultURL, "sets the manifest URL")
+	rootCmd.PersistentFlags().StringVar(&manifestURL, "manifest", manifest.DefaultURL, "sets the manifest URL")
+	rootCmd.PersistentFlags().MarkHidden("manifest") // nolint
 	return rootCmd
 }
 
 var (
 	rootCmd = &cobra.Command{
 		Use:   "getenvoy",
-		Short: "getenvoy",
-		Long:  "getenvoy",
+		Short: "Fetch, deploy and debug Envoy",
+		Long: `Manage full lifecycle of Envoy including fetching binaries,
+bootstrap generation and automated collection of access logs, Envoy state and machine state.`,
 	}
 
 	manifestURL string

pkg/cmd/run.go

@@ -37,18 +37,21 @@ var (
 // NewRunCmd create a command responsible for starting an Envoy process
 func NewRunCmd() *cobra.Command {
 	cmd := &cobra.Command{
-		Use:   "run [manifest-reference|filepath] -- <envoy-args>",
-		Short: "Starts an Envoy process using the reference or path passed.",
+		Use:   "run <reference|filepath> [flags] [-- <envoy-args>]",
+		Short: "Runs an instance of Envoy.",
 		Long: `
-Starts an Envoy process using the location passed. 
-Location can be a manifest reference or path to an Envoy binary.`,
-		Example: `# Run using a manifest reference. Reference format is <flavor>:<version>.
+Manages full lifecycle of Envoy including bootstrap generation and automated collection of access logs,
+Envoy state and machine state into the ` + "`~/.getenvoy/debug`" + ` directory.`,
+		Example: `# Run using a manifest reference.
 getenvoy run standard:1.11.1 -- --config-path ./bootstrap.yaml
 
-# Run using a filepath
+# Run as a gateway using an Istio controlplane bootstrap.
+getenvoy run standard:1.11.1 --mode router --bootstrap istio --controlplaneAddress istio-pilot.istio-system:15010
+
+# Run using a filepath.
 getenvoy run ./envoy -- --config-path ./bootstrap.yaml
 
-# List available Envoy flags
+# List available Envoy flags.
 getenvoy run standard:1.11.1 -- --help
 `,
 		Args: func(cmd *cobra.Command, args []string) error {
@@ -103,13 +106,13 @@ getenvoy run standard:1.11.1 -- --help
 		},
 	}
 	cmd.Flags().StringVarP(&bootstrap, "bootstrap", "b", "",
-		fmt.Sprintf("which controlplane's bootstrap to generate and use (%v) [experimental]", strings.Join(supported, "|")))
+		fmt.Sprintf("controlplane bootstrap to generate and use <%v> (experimental)", strings.Join(supported, "|")))
 	cmd.Flags().StringVar(&controlplaneAddress, "controlplaneAddress", "",
-		"location of Envoy's dynamic configuration server (<host|ip>:port) [requires bootstrap to be set]")
+		"location of Envoy's dynamic configuration server <host|ip:port> (requires bootstrap flag)")
 	cmd.Flags().StringVar(&accessLogServerAddress, "accessLogServerAddress", "",
-		"location of Envoy's access log server(<host|ip>:port) [requires bootstrap to be set]")
-	cmd.Flags().StringVarP(&mode, "mode", "m", "",
-		fmt.Sprintf("mode to run Envoy in (%v) [requires bootstrap to be set]", strings.Join(envoy.SupportedModes, "|")))
+		"location of Envoy's access log server <host|ip:port> (requires bootstrap flag)")
+	cmd.Flags().StringVar(&mode, "mode", "",
+		fmt.Sprintf("mode to run Envoy in <%v> (requires bootstrap flag)", strings.Join(envoy.SupportedModes, "|")))
 	return cmd
 }