Add gendocs ci step

cmoog · cmoog · commit 0e031d9e16b8 · 2020-08-14T09:26:13.000-05:00
diff --git a/.github/workflows/test.yaml b/.github/workflows/test.yaml
@@ -44,3 +44,17 @@ jobs:
         uses: ./ci/image
         with:
           args: go test ./internal/... ./cmd/...
+  gendocs:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v1
+      - uses: actions/cache@v1
+        with:
+          path: ~/go/pkg/mod
+          key: ${{ runner.os }}-go-${{ hashFiles('**/go.sum') }}
+          restore-keys: |
+            ${{ runner.os }}-go-
+      - name: generate-docs
+        uses: ./ci/image
+        with:
+          args: ./ci/steps/gendocs.sh
diff --git a/ci/steps/fmt.sh b/ci/steps/fmt.sh
@@ -1,16 +1,17 @@
 #!/bin/bash
+
+set -euo pipefail
+
 echo "Formatting..."
 
 go mod tidy
 gofmt -w -s .
 goimports -w "-local=$$(go list -m)" .
 
-if [ "$CI" != "" ]; then
-  if [[ $(git ls-files --other --modified --exclude-standard) != "" ]]; then
+if [[ ${CI-} && $(git ls-files --other --modified --exclude-standard) ]]; then
     echo "Files need generation or are formatted incorrectly:"
     git -c color.ui=always status | grep --color=no '\e\[31m'
     echo "Please run the following locally:"
     echo "  ./ci/steps/fmt.sh"
     exit 1
   fi
-fi
diff --git a/ci/steps/gendocs.sh b/ci/steps/gendocs.sh
@@ -0,0 +1,25 @@
+#!/bin/bash
+
+set -euo pipefail
+
+echo "Generating docs..."
+
+cd "$(dirname "$0")"
+cd ../../
+
+go run ./cmd/coder gen-docs ./docs
+
+# remove cobra footer from each file
+for filename in ./docs/*.md; do
+  trimmed=$(head -n -1 "$filename")
+  echo "$trimmed" > $filename
+done
+
+
+if [[ ${CI-} && $(git ls-files --other --modified --exclude-standard) ]]; then
+  echo "Documentation needs generation:"
+  git -c color.ui=always status | grep --color=no '\e\[31m'
+  echo "Please run the following locally:"
+  echo "  ./ci/steps/gendocs.sh"
+  exit 1
+fi
diff --git a/ci/steps/lint.sh b/ci/steps/lint.sh
@@ -1,6 +1,8 @@
 #!/bin/bash
 
+set -euo pipefail
+
 echo "Linting..."
 
 go vet ./...
-golint -set_exit_status ./...
+golint -set_exit_status ./...
diff --git a/docs/coder.md b/docs/coder.md
@@ -14,6 +14,7 @@ coder provides a CLI for working with an existing Coder Enterprise installation
 
 ### SEE ALSO
 
+* [coder completion](coder_completion.md)	 - Generate completion script
 * [coder config-ssh](coder_config-ssh.md)	 - Configure SSH to access Coder environments
 * [coder envs](coder_envs.md)	 - Interact with Coder environments
 * [coder login](coder_login.md)	 - Authenticate this client for future operations
@@ -23,4 +24,3 @@ coder provides a CLI for working with an existing Coder Enterprise installation
 * [coder sync](coder_sync.md)	 - Establish a one way directory sync to a Coder environment
 * [coder urls](coder_urls.md)	 - Interact with environment DevURLs
 * [coder users](coder_users.md)	 - Interact with Coder user accounts
-
diff --git a/docs/coder_completion.md b/docs/coder_completion.md
@@ -0,0 +1,63 @@
+## coder completion
+
+Generate completion script
+
+### Synopsis
+
+To load completions:
+
+Bash:
+
+$ source <(coder completion bash)
+
+To load completions for each session, execute once:
+Linux:
+  $ coder completion bash > /etc/bash_completion.d/coder
+MacOS:
+  $ coder completion bash > /usr/local/etc/bash_completion.d/coder
+
+Zsh:
+
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
+
+$ echo "autoload -U compinit; compinit" >> ~/.zshrc
+
+To load completions for each session, execute once:
+$ coder completion zsh > "${fpath[1]}/_coder"
+
+You will need to start a new shell for this setup to take effect.
+
+Fish:
+
+$ coder completion fish | source
+
+To load completions for each session, execute once:
+$ coder completion fish > ~/.config/fish/completions/coder.fish
+
+
+```
+coder completion [bash|zsh|fish|powershell]
+```
+
+### Examples
+
+```
+coder completion fish > ~/.config/fish/completions/coder.fish
+coder completion zsh > "${fpath[1]}/_coder"
+
+Linux:
+  $ coder completion bash > /etc/bash_completion.d/coder
+MacOS:
+  $ coder completion bash > /usr/local/etc/bash_completion.d/coder
+```
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### SEE ALSO
+
+* [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
diff --git a/docs/coder_config-ssh.md b/docs/coder_config-ssh.md
@@ -21,4 +21,3 @@ coder config-ssh [flags]
 ### SEE ALSO
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
-
diff --git a/docs/coder_envs.md b/docs/coder_envs.md
@@ -17,4 +17,3 @@ Perform operations on the Coder environments owned by the active user.
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
 * [coder envs ls](coder_envs_ls.md)	 - list all environments owned by the active user
-
diff --git a/docs/coder_envs_ls.md b/docs/coder_envs_ls.md
@@ -26,4 +26,3 @@ coder envs ls [flags]
 ### SEE ALSO
 
 * [coder envs](coder_envs.md)	 - Interact with Coder environments
-
diff --git a/docs/coder_login.md b/docs/coder_login.md
@@ -19,4 +19,3 @@ coder login [Coder Enterprise URL eg. http://my.coder.domain/] [flags]
 ### SEE ALSO
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
-
diff --git a/docs/coder_logout.md b/docs/coder_logout.md
@@ -19,4 +19,3 @@ coder logout [flags]
 ### SEE ALSO
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
-
diff --git a/docs/coder_secrets.md b/docs/coder_secrets.md
@@ -20,4 +20,3 @@ Interact with secrets objects owned by the active user.
 * [coder secrets ls](coder_secrets_ls.md)	 - List all secrets owned by the active user
 * [coder secrets rm](coder_secrets_rm.md)	 - Remove one or more secrets by name
 * [coder secrets view](coder_secrets_view.md)	 - View a secret by name
-
diff --git a/docs/coder_secrets_create.md b/docs/coder_secrets_create.md
@@ -37,4 +37,3 @@ coder secrets create aws-credentials --from-file ./credentials.json
 ### SEE ALSO
 
 * [coder secrets](coder_secrets.md)	 - Interact with Coder Secrets
-
diff --git a/docs/coder_secrets_ls.md b/docs/coder_secrets_ls.md
@@ -25,4 +25,3 @@ coder secrets ls [flags]
 ### SEE ALSO
 
 * [coder secrets](coder_secrets.md)	 - Interact with Coder Secrets
-
diff --git a/docs/coder_secrets_rm.md b/docs/coder_secrets_rm.md
@@ -31,4 +31,3 @@ coder secrets rm mysql-password mysql-user
 ### SEE ALSO
 
 * [coder secrets](coder_secrets.md)	 - Interact with Coder Secrets
-
diff --git a/docs/coder_secrets_view.md b/docs/coder_secrets_view.md
@@ -31,4 +31,3 @@ coder secrets view mysql-password
 ### SEE ALSO
 
 * [coder secrets](coder_secrets.md)	 - Interact with Coder Secrets
-
diff --git a/docs/coder_sh.md b/docs/coder_sh.md
@@ -25,4 +25,3 @@ coder sh backend-env
 ### SEE ALSO
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
-
diff --git a/docs/coder_sync.md b/docs/coder_sync.md
@@ -20,4 +20,3 @@ coder sync [local directory] [<env name>:<remote directory>] [flags]
 ### SEE ALSO
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
-
diff --git a/docs/coder_urls.md b/docs/coder_urls.md
@@ -18,4 +18,3 @@ Interact with environment DevURLs
 * [coder urls create](coder_urls_create.md)	 - Create a new devurl for an environment
 * [coder urls ls](coder_urls_ls.md)	 - List all DevURLs for an environment
 * [coder urls rm](coder_urls_rm.md)	 - Remove a dev url
-
diff --git a/docs/coder_urls_create.md b/docs/coder_urls_create.md
@@ -21,4 +21,3 @@ coder urls create [env_name] [port] [--access <level>] [--name <name>] [flags]
 ### SEE ALSO
 
 * [coder urls](coder_urls.md)	 - Interact with environment DevURLs
-
diff --git a/docs/coder_urls_ls.md b/docs/coder_urls_ls.md
@@ -20,4 +20,3 @@ coder urls ls [environment_name] [flags]
 ### SEE ALSO
 
 * [coder urls](coder_urls.md)	 - Interact with environment DevURLs
-
diff --git a/docs/coder_urls_rm.md b/docs/coder_urls_rm.md
@@ -19,4 +19,3 @@ coder urls rm [environment_name] [port] [flags]
 ### SEE ALSO
 
 * [coder urls](coder_urls.md)	 - Interact with environment DevURLs
-
diff --git a/docs/coder_users.md b/docs/coder_users.md
@@ -16,4 +16,3 @@ Interact with Coder user accounts
 
 * [coder](coder.md)	 - coder provides a CLI for working with an existing Coder Enterprise installation
 * [coder users ls](coder_users_ls.md)	 - list all user accounts
-
diff --git a/docs/coder_users_ls.md b/docs/coder_users_ls.md
@@ -27,4 +27,3 @@ coder users ls -o json | jq .[] | jq -r .email
 ### SEE ALSO
 
 * [coder users](coder_users.md)	 - Interact with Coder user accounts
-
diff --git a/internal/cmd/cmd.go b/internal/cmd/cmd.go
@@ -4,6 +4,7 @@ import (
 	"os"
 
 	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
 )
 
 // Make constructs the "coder" root command
@@ -24,43 +25,65 @@ func Make() *cobra.Command {
 		makeSyncCmd(),
 		makeURLCmd(),
 		completionCmd,
+		genDocs(app),
 	)
 	return app
 }
 
+func genDocs(rootCmd *cobra.Command) *cobra.Command {
+	cmd := &cobra.Command{
+		Use:     "gen-docs [dir_path]",
+		Short:   "Generate a markdown documentation tree for the root command.",
+		Example: "coder gen-docs ./docs",
+		Args:    cobra.ExactArgs(1),
+		Hidden:  true,
+		RunE: func(_ *cobra.Command, args []string) error {
+			return doc.GenMarkdownTree(rootCmd, args[0])
+		},
+	}
+	return cmd
+}
+
 // reference: https://github.com/spf13/cobra/blob/master/shell_completions.md
 var completionCmd = &cobra.Command{
 	Use:   "completion [bash|zsh|fish|powershell]",
 	Short: "Generate completion script",
+	Example: `coder completion fish > ~/.config/fish/completions/coder.fish
+coder completion zsh > "${fpath[1]}/_coder"
+
+Linux:
+  $ coder completion bash > /etc/bash_completion.d/coder
+MacOS:
+  $ coder completion bash > /usr/local/etc/bash_completion.d/coder`,
 	Long: `To load completions:
 
 Bash:
 
 $ source <(coder completion bash)
 
-# To load completions for each session, execute once:
+To load completions for each session, execute once:
 Linux:
   $ coder completion bash > /etc/bash_completion.d/coder
 MacOS:
   $ coder completion bash > /usr/local/etc/bash_completion.d/coder
 
 Zsh:
 
-# If shell completion is not already enabled in your environment you will need
-# to enable it.  You can execute the following once:
+If shell completion is not already enabled in your environment you will need
+to enable it.  You can execute the following once:
 
 $ echo "autoload -U compinit; compinit" >> ~/.zshrc
 
-# To load completions for each session, execute once:
+To load completions for each session, execute once:
 $ coder completion zsh > "${fpath[1]}/_coder"
 
-# You will need to start a new shell for this setup to take effect.
+You will need to start a new shell for this setup to take effect.
 
 Fish:
 
 $ coder completion fish | source
 
-# To load completions for each session, execute once:
+To load completions for each session, execute once:
 $ coder completion fish > ~/.config/fish/completions/coder.fish
 `,
 	DisableFlagsInUseLine: true,
diff --git a/internal/cmd/configssh.go b/internal/cmd/configssh.go

Original file line number	Diff line number	Diff line change
`@@ -21,4 +21,3 @@ coder config-ssh [flags]`
`21`	`21`	`### SEE ALSO`
`22`	`22`
`23`	`23`	`* [coder](coder.md) - coder provides a CLI for working with an existing Coder Enterprise installation`
`24`		`-`
Original file line number	Diff line number	Diff line change
`@@ -17,4 +17,3 @@ Perform operations on the Coder environments owned by the active user.`
`17`	`17`
`18`	`18`	`* [coder](coder.md) - coder provides a CLI for working with an existing Coder Enterprise installation`
`19`	`19`	`* [coder envs ls](coder_envs_ls.md) - list all environments owned by the active user`
`20`		`-`
Original file line number	Diff line number	Diff line change
`@@ -26,4 +26,3 @@ coder envs ls [flags]`
`26`	`26`	`### SEE ALSO`
`27`	`27`
`28`	`28`	`* [coder envs](coder_envs.md) - Interact with Coder environments`
`29`		`-`
Original file line number	Diff line number	Diff line change
`@@ -19,4 +19,3 @@ coder login [Coder Enterprise URL eg. http://my.coder.domain/] [flags]`
`19`	`19`	`### SEE ALSO`
`20`	`20`
`21`	`21`	`* [coder](coder.md) - coder provides a CLI for working with an existing Coder Enterprise installation`
`22`		`-`