karmadactl: add the ability to automatically generate user guidance documents for the command line

[Fish-pro]

What type of PR is this?

/kind feature

What this PR does / why we need it:

When using Karmadactl, the user lacks the command execution document, now add the ability to automatically generate guidance documents from the code, just need to execute make ctldocsgen, can generate the help document in the code in docs/usergide/commands

➜  make ctldocsgen
go run tools/cmd-docs/main.go

Which issue(s) this PR fixes:
Fixes #

Special notes for your reviewer:

Does this PR introduce a user-facing change?:

NONE

[karmada-bot]

[APPROVALNOTIFIER] This PR is NOT APPROVED

This pull-request has been approved by:
To complete the pull request process, please assign kevin-wangzefeng after the PR has been reviewed.
You can assign the PR to them by writing /assign @kevin-wangzefeng in a comment when ready.

The full list of commands accepted by this bot can be found here.

Details

Needs approval from an approver in each of these files:

• OWNERS

Approvers can indicate their approval by writing /approve in a comment
Approvers can cancel approval by writing /approve cancel in a comment

[Fish-pro]

karmadactl

karmadactl controls a Kubernetes Cluster Federation.

Synopsis

karmadactl controls a Kubernetes Cluster Federation.

karmadactl [flags]

Options

      --add-dir-header                   If true, adds the file directory to the header of the log messages
      --alsologtostderr                  log to standard error as well as files
  -h, --help                             help for karmadactl
      --kubeconfig string                Paths to a kubeconfig. Only required if out-of-cluster.
      --log-backtrace-at traceLocation   when logging hits line file:N, emit a stack trace (default :0)
      --log-dir string                   If non-empty, write log files in this directory
      --log-file string                  If non-empty, use this log file
      --log-file-max-size uint           Defines the maximum size a log file can grow to. Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)
      --logtostderr                      log to standard error instead of files (default true)
      --one-output                       If true, only write logs to their native severity level (vs also writing to each lower severity level)
      --skip-headers                     If true, avoid header prefixes in the log messages
      --skip-log-headers                 If true, avoid headers when opening log files
      --stderrthreshold severity         logs at or above this threshold go to stderr (default 2)
  -v, --v Level                          number for the log level verbosity
      --vmodule moduleSpec               comma-separated list of pattern=N settings for file-filtered logging

SEE ALSO

• karmadactl apply - Apply a configuration to a resource by file name or stdin and propagate them into member clusters
• karmadactl cordon - Mark cluster as unschedulable
• karmadactl deinit - Removes Karmada from Kubernetes
• karmadactl describe - Show details of a specific resource or group of resources in a cluster
• karmadactl exec - Execute a command in a container in a cluster
• karmadactl get - Display one or many resources
• karmadactl init - Install karmada in kubernetes
• karmadactl join - Register a cluster to control plane
• karmadactl logs - Print the logs for a container in a pod in a cluster
• karmadactl promote - Promote resources from legacy clusters to karmada control plane
• karmadactl taint - Update the taints on one or more clusters
• karmadactl uncordon - Mark cluster as schedulable
• karmadactl unjoin - Remove the registration of a cluster from control plane
• karmadactl version - Print the version information

Auto generated by spf13/cobra on 26-Jul-2022

[Fish-pro]

/cc @lonelyCZ @RainbowMango

[Fish-pro]

/cc @Tingtal

[Tingtal]

Pls check my edits on the language. Thanks

[Tingtal]

Suggested change

	--add-dir-header If true, adds the file directory to the header of the log messages
	--add-dir-header If true, add the file directory to the header of the log messages

[Tingtal]

Suggested change

	--log-backtrace-at traceLocation when logging hits line file:N, emit a stack trace (default :0)
	--log-backtrace-at traceLocation When logging hits line file:N, emit a stack trace (default 0)

[Tingtal]

Suggested change

	--alsologtostderr log to standard error as well as files
	--alsologtostderr Log to standard error as well as files

[Tingtal]

Suggested change

	-h, --help help for karmadactl
	-h, --help Help for karmadactl

[Tingtal]

Suggested change

	--log-file-max-size uint Defines the maximum size a log file can grow to. Unit is megabytes. If the value is 0, the maximum file size is unlimited. (default 1800)
	--log-file-max-size uint Define the maximum size a log file can grow to, in unit of megabyte. Value 0 indicates unlimited file size. (Default to 1800)

[Tingtal]

Suggested change

	--force Delete cluster and secret resources even if resources in the cluster targeted for unjoin are not removed successfully.
	--force Delete cluster and secret resources even if resources in the unjoining cluster are not removed successfully.

[Tingtal]

Suggested change

	--wait duration wait for the unjoin command execution process(default 60s), if there is no success after this time, timeout will be returned. (default 1m0s)
	--wait duration Wait for the unjoin command execution to succeed (default to 60s). Execution failures will return timeout.

[Tingtal]

Same changes for this part

[Tingtal]

Suggested change

	-h, --help help for version
	-h, --help Help for version

[Tingtal]

Same changes for this part

[RainbowMango]

I'm not sure if it really helps. @lonelyCZ What's your opinion here? Should we postpone this until the command line tools are stable?

[lonelyCZ]

Should we postpone this until the command line tools are stable?

Yes, now the karmadactl isn't complicated and is developed actively that could be possibly changed frequently.

[Fish-pro]

Pls check my edits on the language. Thanks

@Tingtal thx a lot, All the documents are automatically generated by the code, and I will address the modification suggestions you put forward in the code

[Fish-pro]

Should we postpone this until the command line tools are stable?

Yes, now the karmadactl isn't complicated and is developed actively that could be possibly changed frequently.

@lonelyCZ thx, All documentation is easily generated automatically by code, which is recommended if introduced in the future

[Poor12]

Hi @Fish-pro, in 1.3 version, we have moved docs to our website and I think it's time to move this pr on. Would you like to keep this going？