Generate markdown from commands' help (#489)

* Generate markdown from commands' help
* Generate docs

.github/pull_request_template.md

@@ -6,13 +6,19 @@
 
 ## Development Checklist
 
+<!--
+Not all of these are mandatory or sometimes relevant.
+Please ignore any that don't apply to your PR.
+-->
+
 - [ ] I have added a descriptive title to this PR.
 - [ ] I have squashed related commits together.
 - [ ] I have rebased my branch on top of the latest main branch.
 - [ ] I have performed a self-review of my own code.
 - [ ] I have commented on my code, particularly in hard-to-understand areas.
 - [ ] I have added docstring(s) to my code.
 - [ ] I have made corresponding changes to the documentation (docs).
+- [ ] I have updated docs using `make gen-docs` command.
 - [ ] I have added tests for my changes.
 - [ ] I have signed all the commits.
 

Makefile

@@ -128,3 +128,6 @@ gen:
 
 update:
 	@buf mod update
+
+gen-docs:
+	@go run main.go gen-docs

cmd/gen_docs.go

@@ -0,0 +1,29 @@
+package cmd
+
+import (
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+var docOutputDir string
+
+var genDocs = &cobra.Command{
+	Use:    "gen-docs",
+	Short:  "Generate markdown documentation",
+	Hidden: true,
+	Run: func(cmd *cobra.Command, _ []string) {
+		err := doc.GenMarkdownTree(rootCmd, docOutputDir)
+		if err != nil {
+			cmd.PrintErr(err)
+		}
+	},
+}
+
+func init() {
+	rootCmd.AddCommand(genDocs)
+
+	genDocs.Flags().StringVarP(
+		&docOutputDir,
+		"output-dir", "o", "./docs",
+		"Output directory for markdown files")
+}

docs/gatewayd.md

@@ -0,0 +1,23 @@
+## gatewayd
+
+A cloud-native database gateway and framework for building data-driven applications
+
+### Synopsis
+
+GatewayD is a cloud-native database gateway and framework for building data-driven applications. It sits between your database servers and clients and proxies all their communication.
+
+### Options
+
+```
+  -h, --help   help for gatewayd
+```
+
+### SEE ALSO
+
+* [gatewayd completion](gatewayd_completion.md)	 - Generate the autocompletion script for the specified shell
+* [gatewayd config](gatewayd_config.md)	 - Manage GatewayD global configuration
+* [gatewayd plugin](gatewayd_plugin.md)	 - Manage plugins and their configuration
+* [gatewayd run](gatewayd_run.md)	 - Run a GatewayD instance
+* [gatewayd version](gatewayd_version.md)	 - Show version information
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_completion.md

@@ -0,0 +1,25 @@
+## gatewayd completion
+
+Generate the autocompletion script for the specified shell
+
+### Synopsis
+
+Generate the autocompletion script for gatewayd for the specified shell.
+See each sub-command's help for details on how to use the generated script.
+
+
+### Options
+
+```
+  -h, --help   help for completion
+```
+
+### SEE ALSO
+
+* [gatewayd](gatewayd.md)	 - A cloud-native database gateway and framework for building data-driven applications
+* [gatewayd completion bash](gatewayd_completion_bash.md)	 - Generate the autocompletion script for bash
+* [gatewayd completion fish](gatewayd_completion_fish.md)	 - Generate the autocompletion script for fish
+* [gatewayd completion powershell](gatewayd_completion_powershell.md)	 - Generate the autocompletion script for powershell
+* [gatewayd completion zsh](gatewayd_completion_zsh.md)	 - Generate the autocompletion script for zsh
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_completion_bash.md

@@ -0,0 +1,44 @@
+## gatewayd completion bash
+
+Generate the autocompletion script for bash
+
+### Synopsis
+
+Generate the autocompletion script for the bash shell.
+
+This script depends on the 'bash-completion' package.
+If it is not installed already, you can install it via your OS's package manager.
+
+To load completions in your current shell session:
+
+	source <(gatewayd completion bash)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	gatewayd completion bash > /etc/bash_completion.d/gatewayd
+
+#### macOS:
+
+	gatewayd completion bash > $(brew --prefix)/etc/bash_completion.d/gatewayd
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+gatewayd completion bash
+```
+
+### Options
+
+```
+  -h, --help              help for bash
+      --no-descriptions   disable completion descriptions
+```
+
+### SEE ALSO
+
+* [gatewayd completion](gatewayd_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_completion_fish.md

@@ -0,0 +1,35 @@
+## gatewayd completion fish
+
+Generate the autocompletion script for fish
+
+### Synopsis
+
+Generate the autocompletion script for the fish shell.
+
+To load completions in your current shell session:
+
+	gatewayd completion fish | source
+
+To load completions for every new session, execute once:
+
+	gatewayd completion fish > ~/.config/fish/completions/gatewayd.fish
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+gatewayd completion fish [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for fish
+      --no-descriptions   disable completion descriptions
+```
+
+### SEE ALSO
+
+* [gatewayd completion](gatewayd_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_completion_powershell.md

@@ -0,0 +1,32 @@
+## gatewayd completion powershell
+
+Generate the autocompletion script for powershell
+
+### Synopsis
+
+Generate the autocompletion script for powershell.
+
+To load completions in your current shell session:
+
+	gatewayd completion powershell | Out-String | Invoke-Expression
+
+To load completions for every new session, add the output of the above command
+to your powershell profile.
+
+
+```
+gatewayd completion powershell [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for powershell
+      --no-descriptions   disable completion descriptions
+```
+
+### SEE ALSO
+
+* [gatewayd completion](gatewayd_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_completion_zsh.md

@@ -0,0 +1,46 @@
+## gatewayd completion zsh
+
+Generate the autocompletion script for zsh
+
+### Synopsis
+
+Generate the autocompletion script for the zsh shell.
+
+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 in your current shell session:
+
+	source <(gatewayd completion zsh)
+
+To load completions for every new session, execute once:
+
+#### Linux:
+
+	gatewayd completion zsh > "${fpath[1]}/_gatewayd"
+
+#### macOS:
+
+	gatewayd completion zsh > $(brew --prefix)/share/zsh/site-functions/_gatewayd
+
+You will need to start a new shell for this setup to take effect.
+
+
+```
+gatewayd completion zsh [flags]
+```
+
+### Options
+
+```
+  -h, --help              help for zsh
+      --no-descriptions   disable completion descriptions
+```
+
+### SEE ALSO
+
+* [gatewayd completion](gatewayd_completion.md)	 - Generate the autocompletion script for the specified shell
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_config.md

@@ -0,0 +1,21 @@
+## gatewayd config
+
+Manage GatewayD global configuration
+
+```
+gatewayd config [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for config
+```
+
+### SEE ALSO
+
+* [gatewayd](gatewayd.md)	 - A cloud-native database gateway and framework for building data-driven applications
+* [gatewayd config init](gatewayd_config_init.md)	 - Create or overwrite the GatewayD global config
+* [gatewayd config lint](gatewayd_config_lint.md)	 - Lint the GatewayD global config
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_config_init.md

@@ -0,0 +1,22 @@
+## gatewayd config init
+
+Create or overwrite the GatewayD global config
+
+```
+gatewayd config init [flags]
+```
+
+### Options
+
+```
+  -c, --config string   Global config file (default "gatewayd.yaml")
+  -f, --force           Force overwrite of existing config file
+  -h, --help            help for init
+      --sentry          Enable Sentry (default true)
+```
+
+### SEE ALSO
+
+* [gatewayd config](gatewayd_config.md)	 - Manage GatewayD global configuration
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_config_lint.md

@@ -0,0 +1,21 @@
+## gatewayd config lint
+
+Lint the GatewayD global config
+
+```
+gatewayd config lint [flags]
+```
+
+### Options
+
+```
+  -c, --config string   Global config file (default "gatewayd.yaml")
+  -h, --help            help for lint
+      --sentry          Enable Sentry (default true)
+```
+
+### SEE ALSO
+
+* [gatewayd config](gatewayd_config.md)	 - Manage GatewayD global configuration
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_plugin.md

@@ -0,0 +1,23 @@
+## gatewayd plugin
+
+Manage plugins and their configuration
+
+```
+gatewayd plugin [flags]
+```
+
+### Options
+
+```
+  -h, --help   help for plugin
+```
+
+### SEE ALSO
+
+* [gatewayd](gatewayd.md)	 - A cloud-native database gateway and framework for building data-driven applications
+* [gatewayd plugin init](gatewayd_plugin_init.md)	 - Create or overwrite the GatewayD plugins config
+* [gatewayd plugin install](gatewayd_plugin_install.md)	 - Install a plugin from a local archive or a GitHub repository
+* [gatewayd plugin lint](gatewayd_plugin_lint.md)	 - Lint the GatewayD plugins config
+* [gatewayd plugin list](gatewayd_plugin_list.md)	 - List the GatewayD plugins
+
+###### Auto generated by spf13/cobra on 8-Mar-2024

docs/gatewayd_plugin_init.md

@@ -0,0 +1,22 @@
+## gatewayd plugin init
+
+Create or overwrite the GatewayD plugins config
+
+```
+gatewayd plugin init [flags]
+```
+
+### Options
+
+```
+  -f, --force                  Force overwrite of existing config file
+  -h, --help                   help for init
+  -p, --plugin-config string   Plugin config file (default "gatewayd_plugins.yaml")
+      --sentry                 Enable Sentry (default true)
+```
+
+### SEE ALSO
+
+* [gatewayd plugin](gatewayd_plugin.md)	 - Manage plugins and their configuration
+
+###### Auto generated by spf13/cobra on 8-Mar-2024