feat(cli): Generate documentation automatically (#55)

Makefile

@@ -1,7 +1,7 @@
 SHELL=/bin/bash -o pipefail
 
 .PHONY: build
-build:
+build: docs
 	go build -mod=vendor -o meroxa
 
 .PHONY: install
@@ -15,4 +15,8 @@ gomod:
 
 .PHONY: test
 test:
-	go test -v ${GO_TEST_FLAGS} -count=1 ./...
+	go test -v ${GO_TEST_FLAGS} -count=1 ./...
+
+.PHONY: docs
+docs:
+	go run tools/make-docs/main.go	

README.md

@@ -69,6 +69,9 @@ git tag is pushed to the repo.
 * Tag - `git tag -a vX.X.X -m "<message goes here>"`
 * Push - `git push origin vX.X.X`
 
+### Documentation
+
+Our Meroxa CLI is documented publicly in https://docs.meroxa.com/docs, but on each build we also generate Markdown files for each command, exposing the available commands and help for each one. Check it out at [docs/commands/meroxa](docs/commands/meroxa.md).
 ### Test
 
 _TODO_

cmd/add.go

@@ -102,7 +102,7 @@ var addResourceCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(addCmd)
+	RootCmd.AddCommand(addCmd)
 	addCmd.AddCommand(addResourceCmd)
 
 	addResourceCmd.Flags().StringVarP(&resName, "name", "n", "foo", "resource name")

cmd/auth.go

@@ -158,18 +158,18 @@ var whoAmICmd = &cobra.Command{
 
 func init() {
 	// Login
-	rootCmd.AddCommand(loginCmd)
+	RootCmd.AddCommand(loginCmd)
 	loginCmd.PersistentFlags().StringVar(&flagLoginUsername, "username", "", "username")
 	loginCmd.PersistentFlags().StringVar(&flagLoginPassword, "password", "", "password")
 
 	// Subcommands
 	loginCmd.AddCommand(whoAmICmd)
 
 	// Logout
-	rootCmd.AddCommand(logoutCmd)
+	RootCmd.AddCommand(logoutCmd)
 
 	// Signup
-	rootCmd.AddCommand(signupCmd)
+	RootCmd.AddCommand(signupCmd)
 	signupCmd.PersistentFlags().StringVar(&flagSignupUsername, "username", "", "username")
 	signupCmd.PersistentFlags().StringVar(&flagSignupPassword, "password", "", "password")
 	signupCmd.PersistentFlags().StringVar(&flagSignupEmail, "email", "", "email")

cmd/completion.go

@@ -58,5 +58,5 @@ var completionCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(completionCmd)
+	RootCmd.AddCommand(completionCmd)
 }

cmd/connect.go

@@ -96,7 +96,7 @@ source to Meroxa and creating a connector from Meroxa to the target`,
 }
 
 func init() {
-	rootCmd.AddCommand(connectCmd)
+	RootCmd.AddCommand(connectCmd)
 
 	// Subcommands
 	connectCmd.Flags().String("to", "", "target resource name")

cmd/create.go

@@ -157,7 +157,7 @@ var createPipelineCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(createCmd)
+	RootCmd.AddCommand(createCmd)
 
 	createCmd.AddCommand(createConnectorCmd)
 	createConnectorCmd.Flags().StringP("name", "n", "", "connector name")

cmd/delete.go

@@ -158,7 +158,7 @@ var deletePipelineCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(deleteCmd)
+	RootCmd.AddCommand(deleteCmd)
 
 	// Subcommands
 	deleteCmd.AddCommand(deleteResourceCmd)

cmd/describe.go

@@ -102,7 +102,7 @@ var describeConnectorCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(describeCmd)
+	RootCmd.AddCommand(describeCmd)
 
 	// Subcommands
 	describeCmd.AddCommand(describeResourceCmd)

cmd/list.go

@@ -140,7 +140,7 @@ var listPipelinesCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(listCmd)
+	RootCmd.AddCommand(listCmd)
 
 	// Subcommands
 	listCmd.AddCommand(listResourcesCmd)

cmd/log.go

@@ -9,7 +9,7 @@ import (
 )
 
 func init() {
-	rootCmd.AddCommand(logsCmd)
+	RootCmd.AddCommand(logsCmd)
 	logsCmd.AddCommand(logsConnectorCmd)
 }
 

cmd/root.go

@@ -1,20 +1,19 @@
-package cmd
-
 /*
 Copyright © 2020 Meroxa Inc
 
 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
+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"
@@ -33,10 +32,10 @@ var (
 	flagRootOutputJSON bool
 )
 
-// rootCmd represents the base command when called without any subcommands
-var rootCmd = &cobra.Command{
+// RootCmd represents the base command when called without any subcommands
+var RootCmd = &cobra.Command{
 	Use:   "meroxa",
-	Short: "the Meroxa CLI",
+	Short: "The Meroxa CLI",
 	Long: `The Meroxa CLI allows quick and easy access to the Meroxa data platform.
 
 Using the CLI you are able to create and manage sophisticated data pipelines
@@ -47,19 +46,19 @@ meroxa list resource-types`,
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.
-// This is called by main.main(). It only needs to happen once to the rootCmd.
+// This is called by main.main(). It only needs to happen once to the RootCmd.
 func Execute(version string) {
 	meroxaVersion = version
-	if err := rootCmd.Execute(); err != nil {
+	if err := RootCmd.Execute(); err != nil {
 		os.Exit(1)
 	}
 }
 
 func init() {
 	cobra.OnInitialize(initConfig)
 
-	rootCmd.PersistentFlags().BoolVar(&flagRootOutputJSON, "json", false, "output json")
-	rootCmd.SilenceUsage = true
+	RootCmd.PersistentFlags().BoolVar(&flagRootOutputJSON, "json", false, "output json")
+	RootCmd.SilenceUsage = true
 }
 
 // initConfig reads in config file and ENV variables if set.

cmd/version.go

@@ -32,7 +32,7 @@ var versionCmd = &cobra.Command{
 }
 
 func init() {
-	rootCmd.AddCommand(versionCmd)
+	RootCmd.AddCommand(versionCmd)
 }
 
 func versionString() string {

docs/commands/meroxa.md

@@ -0,0 +1,37 @@
+## meroxa
+
+The Meroxa CLI
+
+### Synopsis
+
+The Meroxa CLI allows quick and easy access to the Meroxa data platform.
+
+Using the CLI you are able to create and manage sophisticated data pipelines
+with only a few simple commands. You can get started by listing the supported
+resource types:
+
+meroxa list resource-types
+
+### Options
+
+```
+  -h, --help   help for meroxa
+      --json   output json
+```
+
+### SEE ALSO
+
+* [meroxa add](meroxa_add.md)	 - Add a Meroxa resource
+* [meroxa completion](meroxa_completion.md)	 - Generate completion script
+* [meroxa connect](meroxa_connect.md)	 - Connect two resources together
+* [meroxa create](meroxa_create.md)	 - Create meroxa pipeline components
+* [meroxa delete](meroxa_delete.md)	 - Delete a component
+* [meroxa describe](meroxa_describe.md)	 - Describe a component
+* [meroxa list](meroxa_list.md)	 - List components
+* [meroxa login](meroxa_login.md)	 - Log into the Meroxa platform
+* [meroxa logout](meroxa_logout.md)	 - Logout of the Meroxa platform
+* [meroxa logs](meroxa_logs.md)	 - Print logs for a component
+* [meroxa signup](meroxa_signup.md)	 - Sign up to the Meroxa platform
+* [meroxa version](meroxa_version.md)	 - Display the version of the Meroxa CLI
+
+###### Auto generated by spf13/cobra on 12-Feb-2021

docs/commands/meroxa_add.md

@@ -0,0 +1,26 @@
+## meroxa add
+
+Add a Meroxa resource
+
+### Synopsis
+
+Use the add command to add various Meroxa resources to your account.
+
+### Options
+
+```
+  -h, --help   help for add
+```
+
+### Options inherited from parent commands
+
+```
+      --json   output json
+```
+
+### SEE ALSO
+
+* [meroxa](meroxa.md)	 - The Meroxa CLI
+* [meroxa add resource](meroxa_add_resource.md)	 - Add a resource to your account
+
+###### Auto generated by spf13/cobra on 12-Feb-2021

docs/commands/meroxa_add_resource.md

@@ -0,0 +1,29 @@
+## meroxa add resource
+
+Add a resource to your account
+
+```
+meroxa add resource <resource-type> [flags]
+```
+
+### Options
+
+```
+      --credentials string   resource credentials
+  -h, --help                 help for resource
+  -m, --metadata string      resource metadata
+  -n, --name string          resource name (default "foo")
+  -u, --url string           resource url
+```
+
+### Options inherited from parent commands
+
+```
+      --json   output json
+```
+
+### SEE ALSO
+
+* [meroxa add](meroxa_add.md)	 - Add a Meroxa resource
+
+###### Auto generated by spf13/cobra on 12-Feb-2021

docs/commands/meroxa_completion.md

@@ -0,0 +1,59 @@
+## meroxa completion
+
+Generate completion script
+
+### Synopsis
+
+To load completions:
+
+	Bash:
+
+	$ source <(meroxa completion bash)
+
+	# To load completions for each session, execute once:
+	Linux:
+	  $ meroxa completion bash > /etc/bash_completion.d/meroxa
+	MacOS:
+	  $ meroxa completion bash > /usr/local/etc/bash_completion.d/meroxa
+
+	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:
+	$ meroxa completion zsh > "${fpath[1]}/_meroxa"
+
+	# You will need to start a new shell for this setup to take effect.
+
+	Fish:
+
+	$ meroxa completion fish | source
+
+	# To load completions for each session, execute once:
+	$ meroxa completion fish > ~/.config/fish/completions/meroxa.fish
+
+
+```
+meroxa completion [bash|zsh|fish|powershell]
+```
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### Options inherited from parent commands
+
+```
+      --json   output json
+```
+
+### SEE ALSO
+
+* [meroxa](meroxa.md)	 - The Meroxa CLI
+
+###### Auto generated by spf13/cobra on 12-Feb-2021

docs/commands/meroxa_connect.md

@@ -0,0 +1,38 @@
+## meroxa connect
+
+Connect two resources together
+
+### Synopsis
+
+Use the connect commands to automatically configure the connectors
+required to pull data from one resource (the source) to another
+(the target).
+
+This is essentially a shortcut for creating a connector from the
+source to Meroxa and creating a connector from Meroxa to the target
+
+```
+meroxa connect <name> --to <name> [flags]
+```
+
+### Options
+
+```
+  -c, --config string   connector configuration
+      --from string     source resource name
+  -h, --help            help for connect
+      --input string    command delimeted list of input streams
+      --to string       target resource name
+```
+
+### Options inherited from parent commands
+
+```
+      --json   output json
+```
+
+### SEE ALSO
+
+* [meroxa](meroxa.md)	 - The Meroxa CLI
+
+###### Auto generated by spf13/cobra on 12-Feb-2021