Repository: tetratelabs/getenvoy
Pull request #264 (2021-06-03 02:53:22)

Hosts usage.md locally
This hosts usage.md locally so that it can be used in the README.md.
This controls formatting so that it looks nicer than default.

This also elaborates the main docs to answer common questions.


Patch:
diff --git a/README.md b/README.md
index ea0578d..1f69070 100644
--- a/README.md
+++ b/README.md
@@ -5,6 +5,11 @@
 
 # GetEnvoy
 
-**GetEnvoy is spread across multiple repos. For more details head over to [GetEnvoy.io](https://getenvoy.io/github).**
+GetEnvoy is a CLI which makes running [Envoy](https://www.envoyproxy.io/) easy.
 
-The GetEnvoy project focuses on building, distributing, deploying and maintaining a fleet of Envoys.
+Ex. The following will install and run the latest version of Envoy for you:
+```bash
+$ getenvoy run -c your_envoy_config.yaml
+```
+
+Have a look at the [Usage Docs](site/usage.md) or https://getenvoy.io for more information.
diff --git a/internal/cmd/app.go b/internal/cmd/app.go
index 3afd88c..1339eaf 100644
--- a/internal/cmd/app.go
+++ b/internal/cmd/app.go
@@ -15,6 +15,7 @@
 package cmd
 
 import (
+	"fmt"
 	"net/url"
 	"os/user"
 	"path/filepath"
@@ -34,6 +35,18 @@ func NewApp(o *globals.GlobalOpts) *cli.App {
 	app.Name = "getenvoy"
 	app.HelpName = "getenvoy"
 	app.Usage = `Install and run Envoy`
+	// Keep lines at 77 to address leading indent of 3 in help statements
+	// NOTE: remove indenting ourselves after the first line after urfave/cli#1275.
+	app.UsageText = `To run Envoy, execute ` + "`getenvoy run -c your_envoy_config.yaml`" + `. This
+   downloads and installs the latest version of Envoy for you.
+
+   To list versions of Envoy you can use, execute ` + "`getenvoy versions -a`" + `. To
+   choose one, invoke ` + fmt.Sprintf("`getenvoy use %s`", version.LastKnownEnvoy) + `. This installs into
+   ` + fmt.Sprintf("`$GETENVOY_HOME/versions/%s`", version.LastKnownEnvoy) + `, if not already present.
+
+   You may want to override ` + "`$ENVOY_VERSIONS_URL`" + ` to supply custom builds or
+   otherwise control the source of Envoy binaries. When overriding, validate
+   your JSON first: https://getenvoy.io/envoy-versions-schema.json`
 	app.Version = version.GetEnvoy
 	app.Flags = []cli.Flag{
 		&cli.StringFlag{
@@ -63,7 +76,6 @@ func NewApp(o *globals.GlobalOpts) *cli.App {
 		NewRunCmd(o),
 		NewVersionsCmd(o),
 		NewUseCmd(o),
-		NewDocCmd(),
 	}
 	return app
 }
diff --git a/internal/cmd/doc.go b/internal/cmd/doc.go
deleted file mode 100644
index 6c96659..0000000
--- a/internal/cmd/doc.go
+++ /dev/null
@@ -1,41 +0,0 @@
-// 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"
-	"strings"
-
-	"github.com/urfave/cli/v2"
-)
-
-// NewDocCmd returns command that generates documentation
-func NewDocCmd() *cli.Command {
-	cmd := &cli.Command{
-		Name:   "doc",
-		Usage:  "Generates Markdown documentation for the CLI.",
-		Hidden: true,
-		Action: func(c *cli.Context) error {
-			m, err := c.App.ToMarkdown()
-			m = strings.ReplaceAll(m, "% getenvoy 8\n\n", "") // remove man header until urfave/cli#1275
-			if err != nil {
-				return err
-			}
-			_, err = fmt.Fprintln(c.App.Writer, m)
-			return err
-		},
-	}
-	return cmd
-}
diff --git a/site/README.md b/site/README.md
index e8fd7af..56c0d59 100644
--- a/site/README.md
+++ b/site/README.md
@@ -5,4 +5,7 @@ The following files are hosted on https://getenvoy.io, specifically via [Netlify
 Latest master merge:
 * https://getenvoy.io/install.sh -> [./install.sh](install.sh)
 * https://getenvoy.io/envoy-versions.json -> [./envoy-versions.json](envoy-versions.json)
+  * this is verified by [envoy-versions_test.go](envoy-versions_test.go)
 * https://getenvoy.io/envoy-versions-schema.json -> [./envoy-versions-schema.json](envoy-versions-schema.json)
+* https://www.getenvoy.io/usage/ -> [./usage.md](usage.md)
+  * this is verified by [usage_md_test.go](../internal/cmd/usage_md_test.go)
diff --git a/site/usage.md b/site/usage.md
new file mode 100644
index 0000000..9f3e578
--- /dev/null
+++ b/site/usage.md
@@ -0,0 +1,28 @@
+# GetEnvoy CLI Overview
+To run Envoy, execute `getenvoy run -c your_envoy_config.yaml`. This
+downloads and installs the latest version of Envoy for you.
+
+To list versions of Envoy you can use, execute `getenvoy versions -a`. To
+choose one, invoke `getenvoy use 1.18.3`. This installs into
+`$GETENVOY_HOME/versions/1.18.3`, if not already present.
+
+You may want to override `$ENVOY_VERSIONS_URL` to supply custom builds or
+otherwise control the source of Envoy binaries. When overriding, validate
+your JSON first: https://getenvoy.io/envoy-versions-schema.json
+
+# Commands
+
+| Name | Usage |
+| ---- | ----- |
+| help | Shows how to use a [command] |
+| run | Run Envoy with the given [arguments...], collecting process state on termination |
+| versions | List Envoy versions |
+| use | Sets the current [version] used by the "run" command, installing as necessary |
+| --version, -v | Print the version of GetEnvoy |
+
+# Environment Variables
+
+| Name | Usage | Default |
+| ---- | ----- | ------- |
+| GETENVOY_HOME | GetEnvoy home directory (location of installed versions and run archives) | ${HOME}/.getenvoy |
+| ENVOY_VERSIONS_URL | URL of Envoy versions JSON | https://getenvoy.io/envoy-versions.json |


Test patch:
diff --git a/internal/cmd/doc_test.go b/internal/cmd/doc_test.go
deleted file mode 100644
index 936f91f..0000000
--- a/internal/cmd/doc_test.go
+++ /dev/null
@@ -1,38 +0,0 @@
-// Copyright 2020 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_test
-
-import (
-	"os"
-	"path/filepath"
-	"strings"
-	"testing"
-
-	"github.com/stretchr/testify/require"
-
-	"github.com/tetratelabs/getenvoy/internal/globals"
-	"github.com/tetratelabs/getenvoy/internal/version"
-)
-
-func TestGetEnvoyDoc(t *testing.T) {
-	c, stdout, stderr := newApp(&globals.GlobalOpts{})
-	err := c.Run([]string{"getenvoy", "doc"})
-	require.NoError(t, err)
-	require.Empty(t, stderr)
-
-	want, err := os.ReadFile(filepath.Join("testdata", "getenvoy.md"))
-	require.NoError(t, err)
-	require.Equal(t, strings.ReplaceAll(string(want), "ENVOY_VERSION", version.LastKnownEnvoy), stdout.String())
-}
diff --git a/internal/cmd/testdata/getenvoy.md b/internal/cmd/testdata/getenvoy.md
deleted file mode 100644
index 95d0a25..0000000
--- a/internal/cmd/testdata/getenvoy.md
+++ /dev/null
@@ -1,49 +0,0 @@
-# NAME
-
-getenvoy - Install and run Envoy
-
-# SYNOPSIS
-
-getenvoy
-
-```
-[--envoy-versions-url]=[value]
-[--home-dir]=[value]
-[--version|-v]
-```
-
-**Usage**:
-
-```
-getenvoy [GLOBAL OPTIONS] command [COMMAND OPTIONS] [ARGUMENTS...]
-```
-
-# GLOBAL OPTIONS
-
-**--envoy-versions-url**="": URL of Envoy versions JSON
-
-**--home-dir**="": GetEnvoy home directory (location of installed versions and run archives)
-
-**--version, -v**: print the version
-
-
-# COMMANDS
-
-## help
-
-Shows how to use a [command]
-
-## run
-
-Run Envoy with the given [arguments...], collecting process state on termination
-
-## versions
-
-List Envoy versions
-
-**--all, -a**: Show all versions including ones not yet installed
-
-## use
-
-Sets the current [version] used by the "run" command, installing as necessary
-
diff --git a/internal/cmd/testdata/getenvoy_help.txt b/internal/cmd/testdata/getenvoy_help.txt
index 4050913..c1f1f34 100644
--- a/internal/cmd/testdata/getenvoy_help.txt
+++ b/internal/cmd/testdata/getenvoy_help.txt
@@ -2,7 +2,16 @@ NAME:
    getenvoy - Install and run Envoy
 
 USAGE:
-   getenvoy [global options] command [command options] [arguments...]
+   To run Envoy, execute `getenvoy run -c your_envoy_config.yaml`. This
+   downloads and installs the latest version of Envoy for you.
+
+   To list versions of Envoy you can use, execute `getenvoy versions -a`. To
+   choose one, invoke `getenvoy use {ENVOY_VERSION}`. This installs into
+   `$GETENVOY_HOME/versions/{ENVOY_VERSION}`, if not already present.
+
+   You may want to override `$ENVOY_VERSIONS_URL` to supply custom builds or
+   otherwise control the source of Envoy binaries. When overriding, validate
+   your JSON first: https://getenvoy.io/envoy-versions-schema.json
 
 VERSION:
    dev
diff --git a/internal/cmd/usage_md_test.go b/internal/cmd/usage_md_test.go
new file mode 100644
index 0000000..70d5b7b
--- /dev/null
+++ b/internal/cmd/usage_md_test.go
@@ -0,0 +1,61 @@
+// Copyright 2021 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 (
+	"os"
+	"strings"
+	"testing"
+
+	"github.com/stretchr/testify/require"
+	"github.com/urfave/cli/v2"
+
+	"github.com/tetratelabs/getenvoy/internal/globals"
+)
+
+const siteMarkdownFile = "../../site/usage.md"
+
+// TestUsageMarkdownMatchesCommands is in the "cmd" package because changes here will drift siteMarkdownFile.
+func TestUsageMarkdownMatchesCommands(t *testing.T) {
+	// Use a custom markdown template
+	old := cli.MarkdownDocTemplate
+	defer func() { cli.MarkdownDocTemplate = old }()
+	cli.MarkdownDocTemplate = `# GetEnvoy CLI Overview
+{{ .App.UsageText }}
+
+# Commands
+
+| Name | Usage |
+| ---- | ----- |
+{{range $index, $cmd := .App.VisibleCommands}}{{if $index}}
+{{end}}| {{$cmd.Name}} | {{$cmd.Usage}} |{{end}}
+| --version, -v | Print the version of GetEnvoy |
+
+# Environment Variables
+
+| Name | Usage | Default |
+| ---- | ----- | ------- |
+{{range $index, $option := .App.VisibleFlags}}{{if $index}}
+{{end}}| {{index $option.EnvVars 0}} | {{$option.Usage}} | {{$option.DefaultText}} |{{end}}
+`
+	a := NewApp(&globals.GlobalOpts{})
+	want, err := a.ToMarkdown()
+	require.NoError(t, err)
+	want = strings.ReplaceAll(want, "   ", "") // remove leading indent until urfave/cli#1275
+
+	have, err := os.ReadFile(siteMarkdownFile)
+	require.NoError(t, err)
+	require.Equal(t, want, string(have))
+}
diff --git a/site/envoy-versions_test.go b/site/envoy-versions_test.go
index 12b138d..fcea8ca 100644
--- a/site/envoy-versions_test.go
+++ b/site/envoy-versions_test.go
@@ -1,4 +1,4 @@
-// Copyright 2019 Tetrate
+// Copyright 2021 Tetrate
 //
 // Licensed under the Apache License, Version 2.0 (the "License");
 // you may not use this file except in compliance with the License.