cobra/doc/md_docs_test.go

108 lines
2.9 KiB
Go
Raw Normal View History

package doc
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
import (
"bytes"
"io/ioutil"
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
"os"
"path/filepath"
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
"strings"
"testing"
"github.com/spf13/cobra"
)
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
func TestGenMdDoc(t *testing.T) {
c := initializeWithRootCmd()
// Need two commands to run the command alphabetical sort
cmdEcho.AddCommand(cmdTimes, cmdEchoSub, cmdDeprecated)
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
c.AddCommand(cmdPrint, cmdEcho)
cmdRootWithRun.PersistentFlags().StringVarP(&flags2a, "rootflag", "r", "two", strtwoParentHelp)
out := new(bytes.Buffer)
// We generate on s subcommand so we have both subcommands and parents
if err := GenMarkdown(cmdEcho, out); err != nil {
t.Fatal(err)
}
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
found := out.String()
// Our description
expected := cmdEcho.Long
if !strings.Contains(found, expected) {
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
}
// Better have our example
expected = cmdEcho.Example
if !strings.Contains(found, expected) {
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
}
// A local flag
expected = "boolone"
if !strings.Contains(found, expected) {
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
}
// persistent flag on parent
expected = "rootflag"
if !strings.Contains(found, expected) {
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
}
// We better output info about our parent
expected = cmdRootWithRun.Short
if !strings.Contains(found, expected) {
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
}
// And about subcommands
expected = cmdEchoSub.Short
if !strings.Contains(found, expected) {
t.Errorf("Unexpected response.\nExpecting to contain: \n %q\nGot:\n %q\n", expected, found)
}
unexpected := cmdDeprecated.Short
if strings.Contains(found, unexpected) {
t.Errorf("Unexpected response.\nFound: %v\nBut should not have!!\n", unexpected)
}
Auto generation of markdown docs! An example from the kubernetes project, for the `kubectl config` command, which as subcommands, and flags, and all sorts of stuff, it will generate markdown like so: config modifies .kubeconfig files config modifies .kubeconfig files using subcommands like "kubectl config set current-context my-context" ``` kubectl config SUBCOMMAND ``` ``` --envvar=false: use the .kubeconfig from $KUBECONFIG --global=false: use the .kubeconfig from /home/username -h, --help=false: help for config --kubeconfig="": use a particular .kubeconfig file --local=false: use the .kubeconfig in the current directory ``` ``` --alsologtostderr=false: log to standard error as well as files --api-version="": The API version to use when talking to the server -a, --auth-path="": Path to the auth info file. If missing, prompt the user. Only used if using https. --certificate-authority="": Path to a cert. file for the certificate authority. --client-certificate="": Path to a client key file for TLS. --client-key="": Path to a client key file for TLS. --cluster="": The name of the kubeconfig cluster to use --context="": The name of the kubeconfig context to use --insecure-skip-tls-verify=false: If true, the server's certificate will not be checked for validity. This will make your HTTPS connections insecure. --log_backtrace_at=:0: when logging hits line file:N, emit a stack trace --log_dir=: If non-empty, write log files in this directory --log_flush_frequency=5s: Maximum number of seconds between log flushes --logtostderr=true: log to standard error instead of files --match-server-version=false: Require server version to match client version --namespace="": If present, the namespace scope for this CLI request. --password="": Password for basic authentication to the API server. -s, --server="": The address and port of the Kubernetes API server --stderrthreshold=2: logs at or above this threshold go to stderr --token="": Bearer token for authentication to the API server. --user="": The name of the kubeconfig user to use --username="": Username for basic authentication to the API server. --v=0: log level for V logs --validate=false: If true, use a schema to validate the input before sending it --vmodule=: comma-separated list of pattern=N settings for file-filtered logging ``` * [kubectl](kubectl.md) - kubectl controls the Kubernetes cluster manager * [kubectl config set](kubectl_config_set.md) - Sets an individual value in a .kubeconfig file * [kubectl config set-cluster](kubectl_config_set-cluster.md) - Sets a cluster entry in .kubeconfig * [kubectl config set-context](kubectl_config_set-context.md) - Sets a context entry in .kubeconfig * [kubectl config set-credentials](kubectl_config_set-credentials.md) - Sets a user entry in .kubeconfig * [kubectl config unset](kubectl_config_unset.md) - Unsets an individual value in a .kubeconfig file * [kubectl config use-context](kubectl_config_use-context.md) - Sets the current-context in a .kubeconfig file * [kubectl config view](kubectl_config_view.md) - displays merged .kubeconfig settings or a specified .kubeconfig file.
2015-04-07 03:38:51 +00:00
}
func TestGenMdNoTag(t *testing.T) {
c := initializeWithRootCmd()
// Need two commands to run the command alphabetical sort
cmdEcho.AddCommand(cmdTimes, cmdEchoSub, cmdDeprecated)
c.AddCommand(cmdPrint, cmdEcho)
c.DisableAutoGenTag = true
cmdRootWithRun.PersistentFlags().StringVarP(&flags2a, "rootflag", "r", "two", strtwoParentHelp)
out := new(bytes.Buffer)
if err := GenMarkdown(c, out); err != nil {
t.Fatal(err)
}
found := out.String()
unexpected := "Auto generated"
checkStringOmits(t, found, unexpected)
}
func TestGenMdTree(t *testing.T) {
cmd := &cobra.Command{
Use: "do [OPTIONS] arg1 arg2",
}
tmpdir, err := ioutil.TempDir("", "test-gen-md-tree")
if err != nil {
t.Fatalf("Failed to create tmpdir: %s", err.Error())
}
defer os.RemoveAll(tmpdir)
if err := GenMarkdownTree(cmd, tmpdir); err != nil {
t.Fatalf("GenMarkdownTree failed: %s", err.Error())
}
if _, err := os.Stat(filepath.Join(tmpdir, "do.md")); err != nil {
t.Fatalf("Expected file 'do.md' to exist")
}
}