Generating markdown and html docs from the comments in go files

[yp969803]

What would you like to be added:
We have to research, how can we parse comments in the go files to the markdown and html docs(html docs for the wesite)

• We can write custom parsers
• Is any go packages or tools available for the above, and if available what are the limitations

Why is this needed:
The KMesh project is currently in a sandboxed state and undergoes frequent updates, causing the documentation to become outdated over time. For example, the kmeshctl documentation on the website does not always reflect the latest changes. To ensure that the documentation remains accurate and up-to-date, we aim to automate the documentation creation process, reducing manual effort and improving consistency across updates.

[yp969803]

For kmeshctl we can use "github.com/spf13/cobra/doc", package

var multiplyCmd = &cobra.Command{
	Use:   "multiply [a] [b]",
	Short: "Multiply two numbers",
	Long:  `Multiplies two integers provided as arguments and prints the result.`,
	Args:  cobra.ExactArgs(2),
	Run: func(cmd *cobra.Command, args []string) {
		a := args[0]
		b := args[1]
		fmt.Printf("Result: %s * %s = %s\n", a, b, a)
	},
}

// GenerateDocs generates Markdown documentation
func GenerateDocs() error {
	// Directory to save the docs
	dir := "./docs"
	if err := os.MkdirAll(dir, 0755); err != nil {
		return err
	}
	// Generate Markdown files
	return doc.GenMarkdownTree(rootCmd, dir)
}

Result of generated markdown doc
generated in ./docs/mycli_multiply.md

[yp969803]

We need more research, to get the best approach of doing this, all sugestions are welcome

[LiZhenCheng9527]

We have script that automatically generate markdown files based on kmeshctl comments.

https://github.com/kmesh-net/kmesh/blob/main/hack/gen-kmeshctl-doc.sh

[yp969803]

Oohk, we are using cobra go package for kmeshctl, let the issue be open so we can get more ideas of automating generating docs,

we also need generating monitoring docs based on below go code

tcpConnectionOpenedInWorkload = prometheus.NewGaugeVec(prometheus.GaugeOpts{
		Name: "kmesh_tcp_workload_connections_opened_total",
		Help: "The total number of TCP connections opened to a workload",
	}, workloadLabels)

	tcpConnectionClosedInWorkload = prometheus.NewGaugeVec(
		prometheus.GaugeOpts{
			Name: "kmesh_tcp_workload_connections_closed_total",
			Help: "The total number of TCP connections closed to a workload",
		}, workloadLabels)