From e3aa1665e1e7d1bc3b9f459516a5f6ddb3b9fb28 Mon Sep 17 00:00:00 2001 From: Tharun Date: Fri, 4 Jun 2021 20:18:21 +0530 Subject: [PATCH 1/3] feat(kumactl) generate man pages for the kumactl cli Signed-off-by: Tharun --- app/kumactl/cmd/completion/completion.go | 29 ++++++++++++++++ .../cmd/completion/testdata/bash.golden | 33 +++++++++++++++++++ .../cmd/completion/testdata/zsh.golden | 13 ++++++++ app/kumactl/cmd/root.go | 1 + docs/cmd/kumactl/HELP.md | 1 + 5 files changed, 77 insertions(+) diff --git a/app/kumactl/cmd/completion/completion.go b/app/kumactl/cmd/completion/completion.go index 1f2c9dbc4497..e9644c1d5910 100644 --- a/app/kumactl/cmd/completion/completion.go +++ b/app/kumactl/cmd/completion/completion.go @@ -1,9 +1,13 @@ package completion import ( + "fmt" + "github.com/spf13/cobra" + "github.com/spf13/cobra/doc" kumactl_cmd "github.com/kumahq/kuma/app/kumactl/pkg/cmd" + kuma_version "github.com/kumahq/kuma/pkg/version" ) const completionLong = ` @@ -70,3 +74,28 @@ func newZshCommand(pctx *kumactl_cmd.RootContext) *cobra.Command { } return cmd } + +func NewGenManCommand() *cobra.Command { + var path string + cmd := &cobra.Command{ + Use: "genman", + Short: "Generate man pages for the kuma CLI", + Long: `This command automatically generates up-to-date man pages of kuma's command-line interface.`, + RunE: func(cmd *cobra.Command, args []string) error { + cmd.Root().DisableAutoGenTag = true + header := &doc.GenManHeader{ + Section: "1", + Manual: "Kuma CLI Manual", + Source: fmt.Sprintf("kumactl %s", kuma_version.Build.Version), + } + err := doc.GenManTree(cmd.Root(), header, path) + if err != nil { + return err + } + return nil + }, + } + + cmd.Flags().StringVarP(&path, "output-dir", "o", "/tmp/", "directory to populate with documentation") + return cmd +} diff --git a/app/kumactl/cmd/completion/testdata/bash.golden b/app/kumactl/cmd/completion/testdata/bash.golden index 004878924fa5..6ab5846a75b8 100644 --- a/app/kumactl/cmd/completion/testdata/bash.golden +++ b/app/kumactl/cmd/completion/testdata/bash.golden @@ -850,6 +850,38 @@ _kumactl_generate() noun_aliases=() } +_kumactl_genman() +{ + last_command="kumactl_genman" + + command_aliases=() + + commands=() + + flags=() + two_word_flags=() + local_nonpersistent_flags=() + flags_with_completion=() + flags_completion=() + + flags+=("--output-dir=") + two_word_flags+=("--output-dir") + two_word_flags+=("-o") + local_nonpersistent_flags+=("--output-dir=") + flags+=("--config-file=") + two_word_flags+=("--config-file") + flags+=("--log-level=") + two_word_flags+=("--log-level") + flags+=("--mesh=") + two_word_flags+=("--mesh") + two_word_flags+=("-m") + flags+=("--no-config") + + must_have_one_flag=() + must_have_one_noun=() + noun_aliases=() +} + _kumactl_get_circuit-breaker() { last_command="kumactl_get_circuit-breaker" @@ -2768,6 +2800,7 @@ _kumactl_root_command() commands+=("config") commands+=("delete") commands+=("generate") + commands+=("genman") commands+=("get") commands+=("inspect") commands+=("install") diff --git a/app/kumactl/cmd/completion/testdata/zsh.golden b/app/kumactl/cmd/completion/testdata/zsh.golden index bac4b9848e7b..59717082bcbf 100644 --- a/app/kumactl/cmd/completion/testdata/zsh.golden +++ b/app/kumactl/cmd/completion/testdata/zsh.golden @@ -20,6 +20,7 @@ function _kumactl { "config:Manage kumactl config" "delete:Delete Kuma resources" "generate:Generate resources, tokens, etc" + "genman:Generate man pages for the kuma CLI" "get:Show Kuma resources" "help:Help about any command" "inspect:Inspect Kuma resources" @@ -47,6 +48,9 @@ function _kumactl { generate) _kumactl_generate ;; + genman) + _kumactl_genman + ;; get) _kumactl_get ;; @@ -325,6 +329,15 @@ function _kumactl_generate_tls-certificate { '--no-config[if set no config file and config directory will be created]' } +function _kumactl_genman { + _arguments \ + '(-o --output-dir)'{-o,--output-dir}'[directory to populate with documentation]:' \ + '--config-file[path to the configuration file to use]:' \ + '--log-level[log level: one of off|info|debug]:' \ + '(-m --mesh)'{-m,--mesh}'[mesh to use]:' \ + '--no-config[if set no config file and config directory will be created]' +} + function _kumactl_get { local -a commands diff --git a/app/kumactl/cmd/root.go b/app/kumactl/cmd/root.go index e22575404f5d..343b0c818ade 100644 --- a/app/kumactl/cmd/root.go +++ b/app/kumactl/cmd/root.go @@ -97,6 +97,7 @@ func NewRootCmd(root *kumactl_cmd.RootContext) *cobra.Command { cmd.AddCommand(inspect.NewInspectCmd(root)) cmd.AddCommand(install.NewInstallCmd(root)) cmd.AddCommand(uninstall.NewUninstallCmd(root)) + cmd.AddCommand(completion.NewGenManCommand()) cmd.AddCommand(version.NewVersionCmd()) kumactl_cmd.WrapRunnables(cmd, kumactl_errors.FormatErrorWrapper) return cmd diff --git a/docs/cmd/kumactl/HELP.md b/docs/cmd/kumactl/HELP.md index 9a7181eae9e0..db28f5234917 100644 --- a/docs/cmd/kumactl/HELP.md +++ b/docs/cmd/kumactl/HELP.md @@ -12,6 +12,7 @@ Available Commands: config Manage kumactl config delete Delete Kuma resources generate Generate resources, tokens, etc + genman Generate man pages for the kuma CLI get Show Kuma resources help Help about any command inspect Inspect Kuma resources From af52748b08a1309ff7b6d10ab82448df3747da4b Mon Sep 17 00:00:00 2001 From: Tharun Date: Wed, 16 Jun 2021 14:44:57 +0530 Subject: [PATCH 2/3] update docs make file with man pages generation Signed-off-by: Tharun --- app/kumactl/cmd/completion/completion.go | 29 - .../cmd/completion/testdata/bash.golden | 33 - .../cmd/completion/testdata/zsh.golden | 4 - app/kumactl/cmd/root.go | 1 - docs/cmd/kumactl/HELP.md | 842 ------------------ mk/docs.mk | 2 +- tools/docs/generate.go | 46 +- 7 files changed, 41 insertions(+), 916 deletions(-) delete mode 100644 docs/cmd/kumactl/HELP.md diff --git a/app/kumactl/cmd/completion/completion.go b/app/kumactl/cmd/completion/completion.go index e9644c1d5910..1f2c9dbc4497 100644 --- a/app/kumactl/cmd/completion/completion.go +++ b/app/kumactl/cmd/completion/completion.go @@ -1,13 +1,9 @@ package completion import ( - "fmt" - "github.com/spf13/cobra" - "github.com/spf13/cobra/doc" kumactl_cmd "github.com/kumahq/kuma/app/kumactl/pkg/cmd" - kuma_version "github.com/kumahq/kuma/pkg/version" ) const completionLong = ` @@ -74,28 +70,3 @@ func newZshCommand(pctx *kumactl_cmd.RootContext) *cobra.Command { } return cmd } - -func NewGenManCommand() *cobra.Command { - var path string - cmd := &cobra.Command{ - Use: "genman", - Short: "Generate man pages for the kuma CLI", - Long: `This command automatically generates up-to-date man pages of kuma's command-line interface.`, - RunE: func(cmd *cobra.Command, args []string) error { - cmd.Root().DisableAutoGenTag = true - header := &doc.GenManHeader{ - Section: "1", - Manual: "Kuma CLI Manual", - Source: fmt.Sprintf("kumactl %s", kuma_version.Build.Version), - } - err := doc.GenManTree(cmd.Root(), header, path) - if err != nil { - return err - } - return nil - }, - } - - cmd.Flags().StringVarP(&path, "output-dir", "o", "/tmp/", "directory to populate with documentation") - return cmd -} diff --git a/app/kumactl/cmd/completion/testdata/bash.golden b/app/kumactl/cmd/completion/testdata/bash.golden index 4c2567db7583..a777c1d94c54 100644 --- a/app/kumactl/cmd/completion/testdata/bash.golden +++ b/app/kumactl/cmd/completion/testdata/bash.golden @@ -882,38 +882,6 @@ _kumactl_generate() noun_aliases=() } -_kumactl_genman() -{ - last_command="kumactl_genman" - - command_aliases=() - - commands=() - - flags=() - two_word_flags=() - local_nonpersistent_flags=() - flags_with_completion=() - flags_completion=() - - flags+=("--output-dir=") - two_word_flags+=("--output-dir") - two_word_flags+=("-o") - local_nonpersistent_flags+=("--output-dir=") - flags+=("--config-file=") - two_word_flags+=("--config-file") - flags+=("--log-level=") - two_word_flags+=("--log-level") - flags+=("--mesh=") - two_word_flags+=("--mesh") - two_word_flags+=("-m") - flags+=("--no-config") - - must_have_one_flag=() - must_have_one_noun=() - noun_aliases=() -} - _kumactl_get_circuit-breaker() { last_command="kumactl_get_circuit-breaker" @@ -2968,7 +2936,6 @@ _kumactl_root_command() commands+=("config") commands+=("delete") commands+=("generate") - commands+=("genman") commands+=("get") commands+=("inspect") commands+=("install") diff --git a/app/kumactl/cmd/completion/testdata/zsh.golden b/app/kumactl/cmd/completion/testdata/zsh.golden index d54fae143b71..69ccbcca873e 100644 --- a/app/kumactl/cmd/completion/testdata/zsh.golden +++ b/app/kumactl/cmd/completion/testdata/zsh.golden @@ -20,7 +20,6 @@ function _kumactl { "config:Manage kumactl config" "delete:Delete Kuma resources" "generate:Generate resources, tokens, etc" - "genman:Generate man pages for the kuma CLI" "get:Show Kuma resources" "help:Help about any command" "inspect:Inspect Kuma resources" @@ -48,9 +47,6 @@ function _kumactl { generate) _kumactl_generate ;; - genman) - _kumactl_genman - ;; get) _kumactl_get ;; diff --git a/app/kumactl/cmd/root.go b/app/kumactl/cmd/root.go index 343b0c818ade..e22575404f5d 100644 --- a/app/kumactl/cmd/root.go +++ b/app/kumactl/cmd/root.go @@ -97,7 +97,6 @@ func NewRootCmd(root *kumactl_cmd.RootContext) *cobra.Command { cmd.AddCommand(inspect.NewInspectCmd(root)) cmd.AddCommand(install.NewInstallCmd(root)) cmd.AddCommand(uninstall.NewUninstallCmd(root)) - cmd.AddCommand(completion.NewGenManCommand()) cmd.AddCommand(version.NewVersionCmd()) kumactl_cmd.WrapRunnables(cmd, kumactl_errors.FormatErrorWrapper) return cmd diff --git a/docs/cmd/kumactl/HELP.md b/docs/cmd/kumactl/HELP.md deleted file mode 100644 index db28f5234917..000000000000 --- a/docs/cmd/kumactl/HELP.md +++ /dev/null @@ -1,842 +0,0 @@ -# kumactl - -``` -Management tool for Kuma. - -Usage: - kumactl [command] - -Available Commands: - apply Create or modify Kuma resources - completion Output shell completion code for bash, fish or zsh - config Manage kumactl config - delete Delete Kuma resources - generate Generate resources, tokens, etc - genman Generate man pages for the kuma CLI - get Show Kuma resources - help Help about any command - inspect Inspect Kuma resources - install Install various Kuma components. - uninstall Uninstall various Kuma components. - version Print version - -Flags: - --config-file string path to the configuration file to use - -h, --help help for kumactl - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -Use "kumactl [command] --help" for more information about a command. -``` - -## kumactl apply - -``` -Create or modify Kuma resources. - -Usage: - kumactl apply [flags] - -Examples: - -Apply a resource from file -$ kumactl apply -f resource.yaml - -Apply a resource from stdin -$ echo " -type: Mesh -name: demo -" | kumactl apply -f - - -Apply a resource from external URL -$ kumactl apply -f https://example.com/resource.yaml - - -Flags: - --dry-run Resolve variable and prints result out without actual applying - -f, --file - Path to file to apply. Pass - to read from stdin - -h, --help help for apply - -v, --var stringToString Variable to replace in configuration (default []) - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -## kumactl config - -``` -Manage kumactl config. - -Usage: - kumactl config [command] - -Available Commands: - control-planes Manage known Control Planes - view Show kumactl config - -Flags: - -h, --help help for config - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -Use "kumactl config [command] --help" for more information about a command. -``` - -### kumactl config view - -``` -Show kumactl config. - -Usage: - kumactl config view [flags] - -Flags: - -h, --help help for view - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -### kumactl config control-planes - -``` -Manage known Control Planes. - -Usage: - kumactl config control-planes [command] - -Available Commands: - add Add a Control Plane - list List Control Planes - remove Remove a Control Plane - switch Switch active Control Plane - -Flags: - -h, --help help for control-planes - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -Use "kumactl config control-planes [command] --help" for more information about a command. -``` - -#### kumactl config control-planes list - -``` -List Control Planes. - -Usage: - kumactl config control-planes list [flags] - -Flags: - -h, --help help for list - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -#### kumactl config control-planes add - -``` -Add a Control Plane. - -Usage: - kumactl config control-planes add [flags] - -Flags: - --address string URL of the Control Plane API Server (required). Example: http://localhost:5681 or https://localhost:5682) - --ca-cert-file string path to the certificate authority which will be used to verify the Control Plane certificate (kumactl stores only a reference to this file) - --client-cert-file string path to the certificate of a client that is authorized to use the Admin operations of the Control Plane (kumactl stores only a reference to this file) - --client-key-file string path to the certificate key of a client that is authorized to use the Admin operations of the Control Plane (kumactl stores only a reference to this file) - --headers stringToString add these headers while communicating to control plane, format key=value (default []) - -h, --help help for add - --name string reference name for the Control Plane (required) - --overwrite overwrite existing Control Plane with the same reference name - --skip-verify skip CA verification - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -#### kumactl config control-planes remove - -``` -Remove a Control Plane. - -Usage: - kumactl config control-planes remove [flags] - -Flags: - -h, --help help for remove - --name string reference name for the Control Plane (required) - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -#### kumactl config control-planes switch - -``` -Switch active Control Plane. - -Usage: - kumactl config control-planes switch [flags] - -Flags: - -h, --help help for switch - --name string reference name for the Control Plane (required) - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -## kumactl install - -``` -Install various Kuma components. - -Usage: - kumactl install [command] - -Available Commands: - control-plane Install Kuma Control Plane on Kubernetes - crds Install Kuma Custom Resource Definitions on Kubernetes - demo Install Kuma demo on Kubernetes - dns Install DNS to Kubernetes - gateway Install ingress gateway on Kubernetes - logging Install Logging backend in Kubernetes cluster (Loki) - metrics Install Metrics backend in Kubernetes cluster (Prometheus + Grafana) - tracing Install Tracing backend in Kubernetes cluster (Jaeger) - transparent-proxy Install Transparent Proxy pre-requisites on the host - -Flags: - -h, --help help for install - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -Use "kumactl install [command] --help" for more information about a command. -``` - -### kumactl install control-plane - -``` -Install Kuma Control Plane on Kubernetes in a 'kuma-system' namespace. -This command requires that the KUBECONFIG environment is set - -Usage: - kumactl install control-plane [flags] - -Flags: - --cni-bin-dir string set the CNI binary directory (default "/var/lib/cni/bin") - --cni-chained enable chained CNI installation - --cni-conf-name string set the CNI configuration name (default "kuma-cni.conf") - --cni-enabled install Kuma with CNI instead of proxy init container - --cni-net-dir string set the CNI install directory (default "/etc/cni/multus/net.d") - --cni-registry string registry for the image of the Kuma CNI component (default "docker.io/lobkovilya") - --cni-repository string repository for the image of the Kuma CNI component (default "install-cni") - --cni-version string version of the image of the Kuma CNI component (default "0.0.8") - --control-plane-registry string registry for the image of the Kuma Control Plane component (default "docker.io/kumahq") - --control-plane-repository string repository for the image of the Kuma Control Plane component (default "kuma-cp") - --control-plane-service-name string Service name of the Kuma Control Plane (default "kuma-control-plane") - --control-plane-version string version of the image of the Kuma Control Plane component (default "latest") - --dataplane-init-registry string registry for the init image of the Kuma DataPlane component (default "docker.io/kumahq") - --dataplane-init-repository string repository for the init image of the Kuma DataPlane component (default "kuma-init") - --dataplane-init-version string version of the init image of the Kuma DataPlane component (default "latest") - --dataplane-registry string registry for the image of the Kuma DataPlane component (default "docker.io/kumahq") - --dataplane-repository string repository for the image of the Kuma DataPlane component (default "kuma-dp") - --dataplane-version string version of the image of the Kuma DataPlane component (default "latest") - --env-var stringToString environment variables that will be passed to the control plane (default []) - -h, --help help for control-plane - --image-pull-policy string image pull policy that applies to all components of the Kuma Control Plane (default "IfNotPresent") - --ingress-drain-time string drain time for Envoy proxy (default "30s") - --ingress-enabled install Kuma with an Ingress deployment, using the Data Plane image - --ingress-use-node-port use NodePort instead of LoadBalancer for the Ingress Service - --injector-failure-policy string failue policy of the mutating web hook implemented by the Kuma Injector component (default "Ignore") - --kds-global-address string URL of Global Kuma CP (example: grpcs://192.168.0.1:5685) - --mode string kuma cp modes: one of standalone|remote|global (default "standalone") - --namespace string namespace to install Kuma Control Plane to (default "kuma-system") - --tls-api-server-client-certs-secret string Secret that contains list of .pem certificates that can access admin endpoints of Kuma API on HTTPS - --tls-api-server-secret string Secret that contains tls.crt, key.crt for protecting Kuma API on HTTPS - --tls-general-ca-bundle string Base64 encoded CA certificate (the same as in controlPlane.tls.general.secret#ca.crt) - --tls-general-secret string Secret that contains tls.crt, key.crt and ca.crt for protecting Kuma in-cluster communication - --tls-kds-global-server-secret string Secret that contains tls.crt, key.crt for protecting cross cluster communication - --tls-kds-remote-client-secret string Secret that contains ca.crt which was used to sign KDS Global server. Used for CP verification - --use-node-port use NodePort instead of LoadBalancer - --without-kubernetes-connection install without connection to Kubernetes cluster. This can be used for initial Kuma installation, but not for upgrades - --zone string set the Kuma zone name - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -### kumactl install metrics - -``` -Install Metrics backend in Kubernetes cluster (Prometheus + Grafana) in a kuma-metrics namespace - -Usage: - kumactl install metrics [flags] - -Flags: - -h, --help help for metrics - --kuma-cp-address string the address of Kuma CP (default "grpc://kuma-control-plane.kuma-system:5676") - --kuma-prometheus-sd-image string image name of Kuma Prometheus SD (default "docker.io/kumahq/kuma-prometheus-sd") - --kuma-prometheus-sd-version string version of Kuma Prometheus SD (default "latest") - --namespace string namespace to install metrics to (default "kuma-metrics") - --without-grafana disable Grafana resources generation - --without-prometheus disable Prometheus resources generation - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -### kumactl install tracing - -``` -Install Tracing backend in Kubernetes cluster (Jaeger) in a 'kuma-tracing' namespace - -Usage: - kumactl install tracing [flags] - -Flags: - -h, --help help for tracing - --namespace string namespace to install tracing to (default "kuma-tracing") - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -### kumactl generate tls-certificate - -``` -Generate self signed key and certificate pair that can be used for example in Dataplane Token Server setup. - -Usage: - kumactl generate tls-certificate [flags] - -Examples: - - # Generate a TLS certificate for use by an HTTPS server, i.e. by the Dataplane Token server - kumactl generate tls-certificate --type=server - - # Generate a TLS certificate for use by a client of an HTTPS server, i.e. by the 'kumactl generate dataplane-token' command - kumactl generate tls-certificate --type=client - -Flags: - --cert-file string path to a file with a generated TLS certificate (default "cert.pem") - --cp-hostname strings DNS name of the control plane - -h, --help help for tls-certificate - --key-file string path to a file with a generated private key (default "key.pem") - --type string type of the certificate: one of client|server - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -### kumactl generate dataplane-token - -``` -Generate Dataplane Token that is used to prove Dataplane identity. - -Usage: - kumactl generate dataplane-token [flags] - -Examples: - -Generate token bound by name and mesh -$ kumactl generate dataplane-token --mesh demo --name demo-01 - -Generate token bound by mesh -$ kumactl generate dataplane-token --mesh demo - -Generate Ingress token -$ kumactl generate dataplane-token --type ingress - -Generate token bound by tag -$ kumactl generate dataplane-token --mesh demo --tag kuma.io/service=web,web-api - - -Flags: - -h, --help help for dataplane-token - --name string name of the Dataplane - --tag stringToString required tag values for dataplane (split values by comma to provide multiple values) (default []) - --type string type of the Dataplane ("dataplane", "ingress") - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -## kumactl get - -``` -Show Kuma resources. - -Usage: - kumactl get [command] - -Available Commands: - circuit-breaker Show a single CircuitBreaker resource - circuit-breakers Show CircuitBreaker - dataplane Show a single Dataplane resource - dataplanes Show Dataplane - external-service Show a single ExternalService resource - external-services Show ExternalService - fault-injection Show a single FaultInjection resource - fault-injections Show FaultInjection - global-secret Show a single GlobalSecret resource - global-secrets Show GlobalSecret - healthcheck Show a single HealthCheck resource - healthchecks Show HealthCheck - mesh Show a single Mesh resource - meshes Show Mesh - proxytemplate Show a single ProxyTemplate resource - proxytemplates Show ProxyTemplate - retries Show Retry - retry Show a single Retry resource - secret Show a single Secret resource - secrets Show Secret - timeout Show a single Timeout resource - timeouts Show Timeout - traffic-log Show a single TrafficLog resource - traffic-logs Show TrafficLog - traffic-permission Show a single TrafficPermission resource - traffic-permissions Show TrafficPermission - traffic-route Show a single TrafficRoute resource - traffic-routes Show TrafficRoute - traffic-trace Show a single TrafficTrace resource - traffic-traces Show TrafficTrace - zone Show a single Retry resource - zones Show Zone - -Flags: - -h, --help help for get - -o, --output string output format: one of table|yaml|json (default "table") - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -Use "kumactl get [command] --help" for more information about a command. -``` - -### kumactl get meshes - -``` -Show Mesh entities. - -Usage: - kumactl get meshes [flags] - -Flags: - -h, --help help for meshes - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get dataplanes - -``` -Show Dataplane entities. - -Usage: - kumactl get dataplanes [flags] - -Flags: - -h, --help help for dataplanes - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get healthchecks - -``` -Show HealthCheck entities. - -Usage: - kumactl get healthchecks [flags] - -Flags: - -h, --help help for healthchecks - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get retries - -``` -Show Retry entities. - -Usage: - kumactl get retries [flags] - -Flags: - -h, --help help for retries - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get proxytemplates - -``` -Show ProxyTemplate entities. - -Usage: - kumactl get proxytemplates [flags] - -Flags: - -h, --help help for proxytemplates - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get traffic-logs - -``` -Show TrafficLog entities. - -Usage: - kumactl get traffic-logs [flags] - -Flags: - -h, --help help for traffic-logs - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get traffic-permissions - -``` -Show TrafficPermission entities. - -Usage: - kumactl get traffic-permissions [flags] - -Flags: - -h, --help help for traffic-permissions - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get traffic-routes - -``` -Show TrafficRoute entities. - -Usage: - kumactl get traffic-routes [flags] - -Flags: - -h, --help help for traffic-routes - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get traffic-traces - -``` -Show TrafficTrace entities. - -Usage: - kumactl get traffic-traces [flags] - -Flags: - -h, --help help for traffic-traces - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get fault-injections - -``` -Show FaultInjection entities. - -Usage: - kumactl get fault-injections [flags] - -Flags: - -h, --help help for fault-injections - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get secret - -``` -Show a single Secret resource. - -Usage: - kumactl get secret NAME [flags] - -Flags: - -h, --help help for secret - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get secrets - -``` -Show Secret entities. - -Usage: - kumactl get secrets [flags] - -Flags: - -h, --help help for secrets - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl get zones - -``` -Show Zone entities. - -Usage: - kumactl get zones [flags] - -Flags: - -h, --help help for zones - --offset string the offset that indicates starting element of the resources list to retrieve - --size int maximum number of elements to return - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -## kumactl delete - -``` -Delete Kuma resources. - -Usage: - kumactl delete TYPE NAME [flags] - -Flags: - -h, --help help for delete - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - -## kumactl inspect - -``` -Inspect Kuma resources. - -Usage: - kumactl inspect [command] - -Available Commands: - dataplanes Inspect Dataplanes - meshes Inspect Meshes - services Inspect Services - zones Inspect Zones - -Flags: - -h, --help help for inspect - -o, --output string output format: one of table|yaml|json (default "table") - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -Use "kumactl inspect [command] --help" for more information about a command. -``` - -### kumactl inspect dataplanes - -``` -Inspect Dataplanes. - -Usage: - kumactl inspect dataplanes [flags] - -Flags: - --gateway filter gateway dataplanes - -h, --help help for dataplanes - --ingress filter ingress dataplanes - --tag stringToString filter by tag in format of key=value. You can provide many tags (default []) - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -### kumactl inspect zones - -``` -Inspect Zones. - -Usage: - kumactl inspect zones [flags] - -Flags: - -h, --help help for zones - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created - -o, --output string output format: one of table|yaml|json (default "table") -``` - -## kumactl version - -``` -Print version. - -Usage: - kumactl version [flags] - -Flags: - -a, --detailed Print detailed version - -h, --help help for version - -Global Flags: - --config-file string path to the configuration file to use - --log-level string log level: one of off|info|debug (default "off") - -m, --mesh string mesh to use (default "default") - --no-config if set no config file and config directory will be created -``` - diff --git a/mk/docs.mk b/mk/docs.mk index e4453e8be72c..a457e3fdac27 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -12,7 +12,7 @@ docs/install/markdown: ## Generate CLI reference in markdown format .PHONY: docs/install/manpages docs/install/manpages: DESTDIR ?= docs/manpages docs/install/manpages: ## Generate CLI reference in man(1) format - @echo target $@ not implemented + @DESTDIR=$(DESTDIR) FORMAT=man go run ./tools/docs/generate.go .PHONY: docs/install/protobuf docs/install/protobuf: DESTDIR ?= docs/protobuf diff --git a/tools/docs/generate.go b/tools/docs/generate.go index 7810796165a1..4d2310d6a8cd 100644 --- a/tools/docs/generate.go +++ b/tools/docs/generate.go @@ -49,21 +49,55 @@ func markdown(path string, cmd *cobra.Command) { must(doc.GenMarkdownTree(cmd, path)) } +func man(path string, header *doc.GenManHeader, cmd *cobra.Command) { + must(os.MkdirAll(path, 0755)) + must(doc.GenManTree(cmd, header, path)) +} + +type commandWithManHeader struct { + command *cobra.Command + header *doc.GenManHeader +} + func main() { prefix := GetenvOr("DESTDIR", ".") format := GetenvOr("FORMAT", "markdown") - apps := map[string]*cobra.Command{ - path.Join(prefix, "kuma-cp"): kuma_cp.DefaultRootCmd(), - path.Join(prefix, "kumactl"): kumactl.DefaultRootCmd(), - path.Join(prefix, "kuma-dp"): kuma_dp.DefaultRootCmd(), - path.Join(prefix, "kuma-prometheus-sd"): kuma_prometheus_sd.DefaultRootCmd(), + apps := map[string]commandWithManHeader{ + path.Join(prefix, "kuma-cp"): commandWithManHeader{ + command: kuma_cp.DefaultRootCmd(), + header: &doc.GenManHeader{ + Title: "kuma-cp manual", + }, + }, + path.Join(prefix, "kuma-dp"): commandWithManHeader{ + command: kuma_dp.DefaultRootCmd(), + header: &doc.GenManHeader{ + Title: "kuma-dp manual", + }, + }, + path.Join(prefix, "kuma-prometheus-sd"): commandWithManHeader{ + command: kuma_prometheus_sd.DefaultRootCmd(), + header: &doc.GenManHeader{ + Title: "kuma-prometheus-sd manual", + }, + }, + path.Join(prefix, "kumactl"): commandWithManHeader{ + command: kumactl.DefaultRootCmd(), + header: &doc.GenManHeader{ + Title: "kumactl manual", + }, + }, } switch format { case "markdown": for p, c := range apps { - markdown(p, disableAutogen(c)) + markdown(p, disableAutogen(c.command)) + } + case "man": + for p, c := range apps { + man(p, c.header, disableAutogen(c.command)) } default: log.Fatalf("unsupported reference format %q", format) From 1d4281e56bb630098b9b089ed1a9c3fda5b06e53 Mon Sep 17 00:00:00 2001 From: Tharun Date: Wed, 23 Jun 2021 10:34:42 +0530 Subject: [PATCH 3/3] addressed review changes Signed-off-by: Tharun --- mk/docs.mk | 2 +- tools/docs/generate.go | 34 ++++++++++++++++++++++++---------- 2 files changed, 25 insertions(+), 11 deletions(-) diff --git a/mk/docs.mk b/mk/docs.mk index a457e3fdac27..7ed0cd6f3511 100644 --- a/mk/docs.mk +++ b/mk/docs.mk @@ -12,7 +12,7 @@ docs/install/markdown: ## Generate CLI reference in markdown format .PHONY: docs/install/manpages docs/install/manpages: DESTDIR ?= docs/manpages docs/install/manpages: ## Generate CLI reference in man(1) format - @DESTDIR=$(DESTDIR) FORMAT=man go run ./tools/docs/generate.go + @DESTDIR=$(DESTDIR) FORMAT=man $(GO_RUN) ./tools/docs/generate.go .PHONY: docs/install/protobuf docs/install/protobuf: DESTDIR ?= docs/protobuf diff --git a/tools/docs/generate.go b/tools/docs/generate.go index 4d2310d6a8cd..56c61109a981 100644 --- a/tools/docs/generate.go +++ b/tools/docs/generate.go @@ -1,6 +1,7 @@ package main import ( + "fmt" "log" "os" "path" @@ -12,6 +13,7 @@ import ( kuma_dp "github.com/kumahq/kuma/app/kuma-dp/cmd" kuma_prometheus_sd "github.com/kumahq/kuma/app/kuma-prometheus-sd/cmd" kumactl "github.com/kumahq/kuma/app/kumactl/cmd" + "github.com/kumahq/kuma/pkg/version" ) // GetenvOr returns the value of the environment variable named by env, @@ -54,7 +56,7 @@ func man(path string, header *doc.GenManHeader, cmd *cobra.Command) { must(doc.GenManTree(cmd, header, path)) } -type commandWithManHeader struct { +type command struct { command *cobra.Command header *doc.GenManHeader } @@ -63,29 +65,41 @@ func main() { prefix := GetenvOr("DESTDIR", ".") format := GetenvOr("FORMAT", "markdown") - apps := map[string]commandWithManHeader{ - path.Join(prefix, "kuma-cp"): commandWithManHeader{ + apps := map[string]command{ + path.Join(prefix, "kuma-cp"): command{ command: kuma_cp.DefaultRootCmd(), header: &doc.GenManHeader{ - Title: "kuma-cp manual", + Title: "KUMA-CP", + Section: "8", + Source: fmt.Sprintf("%s %s", version.Product, version.Build.Version), + Manual: version.Product, }, }, - path.Join(prefix, "kuma-dp"): commandWithManHeader{ + path.Join(prefix, "kuma-dp"): command{ command: kuma_dp.DefaultRootCmd(), header: &doc.GenManHeader{ - Title: "kuma-dp manual", + Title: "KUMA-DP", + Section: "8", + Source: fmt.Sprintf("%s %s", version.Product, version.Build.Version), + Manual: version.Product, }, }, - path.Join(prefix, "kuma-prometheus-sd"): commandWithManHeader{ + path.Join(prefix, "kuma-prometheus-sd"): command{ command: kuma_prometheus_sd.DefaultRootCmd(), header: &doc.GenManHeader{ - Title: "kuma-prometheus-sd manual", + Title: "KUMA-PROMETHEUS-SD", + Section: "8", + Source: fmt.Sprintf("%s %s", version.Product, version.Build.Version), + Manual: version.Product, }, }, - path.Join(prefix, "kumactl"): commandWithManHeader{ + path.Join(prefix, "kumactl"): command{ command: kumactl.DefaultRootCmd(), header: &doc.GenManHeader{ - Title: "kumactl manual", + Title: "KUMACTL", + Section: "1", + Source: fmt.Sprintf("%s %s", version.Product, version.Build.Version), + Manual: version.Product, }, }, }