From d07b8d27fbef3d6939326f4ce644bd9e9a94be4d Mon Sep 17 00:00:00 2001
From: Michael Geers <michael@geers.tv>
Date: Tue, 1 Oct 2024 15:15:24 +0200
Subject: [PATCH] chore: add gendoc cli cmd (#16436)

---
 cmd/gendock.go | 71 ++++++++++++++++++++++++++++++++++++++++++++++++++
 cmd/root.go    |  2 +-
 go.mod         |  2 ++
 go.sum         |  2 ++
 4 files changed, 76 insertions(+), 1 deletion(-)
 create mode 100644 cmd/gendock.go

diff --git a/cmd/gendock.go b/cmd/gendock.go
new file mode 100644
index 0000000000..fb30e1873e
--- /dev/null
+++ b/cmd/gendock.go
@@ -0,0 +1,71 @@
+package cmd
+
+import (
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+// gendocCmd represents the gendoc command
+var gendocCmd = &cobra.Command{
+	Use:    "gendoc <output-dir>",
+	Short:  "Generate CLI documentation in markdown format",
+	Args:   cobra.ExactArgs(1),
+	Hidden: true,
+	Run:    runGendoc,
+}
+
+func init() {
+	rootCmd.AddCommand(gendocCmd)
+}
+
+func runGendoc(cmd *cobra.Command, args []string) {
+	outputDir := args[0]
+
+	// Ensure the output directory exists
+	if err := os.MkdirAll(outputDir, 0o755); err != nil {
+		log.FATAL.Fatalf("Failed to create output directory: %v", err)
+	}
+
+	if err := doc.GenMarkdownTree(rootCmd, outputDir); err != nil {
+		log.FATAL.Fatalf("Failed to generate documentation: %v", err)
+	}
+
+	// make some modifications to the generated files
+	err := filepath.Walk(outputDir, func(path string, info os.FileInfo, err error) error {
+		if err != nil {
+			return err
+		}
+		if !info.IsDir() && strings.HasSuffix(info.Name(), ".md") {
+			content, err := os.ReadFile(path)
+			if err != nil {
+				return err
+			}
+
+			// reduce header level by one
+			modifiedContent := strings.ReplaceAll(string(content), "## ", "# ")
+			// lowercase "see also"
+			modifiedContent = strings.ReplaceAll(modifiedContent, "SEE ALSO", "See also")
+			// convert single line indented code to backtick surrounded code
+			codeRe := regexp.MustCompile("\n\n\t(.*)\n")
+			modifiedContent = codeRe.ReplaceAllString(modifiedContent, "\n\n```\n$1\n```\n")
+			// remove auto generated date line
+			dateRe := regexp.MustCompile("##### Auto generated by spf13/cobra on.*\n")
+			modifiedContent = dateRe.ReplaceAllString(modifiedContent, "\n")
+
+			if err := os.WriteFile(path, []byte(modifiedContent), 0o644); err != nil {
+				return err
+			}
+		}
+		return nil
+	})
+	if err != nil {
+		log.FATAL.Fatalf("Failed to modify documentation: %v", err)
+	}
+
+	log.INFO.Printf("Documentation generated and modified in %s", outputDir)
+}
diff --git a/cmd/root.go b/cmd/root.go
index 9f7f167bac..4d96e9491a 100644
--- a/cmd/root.go
+++ b/cmd/root.go
@@ -48,7 +48,7 @@ var (
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
 	Use:     "evcc",
-	Short:   "EV Charge Controller",
+	Short:   "evcc - open source solar charging",
 	Version: server.FormattedVersion(),
 	Run:     runRoot,
 }
diff --git a/go.mod b/go.mod
index 611f4dd14a..b963e6ef43 100644
--- a/go.mod
+++ b/go.mod
@@ -117,6 +117,7 @@ require (
 	github.com/beorn7/perks v1.0.1 // indirect
 	github.com/bitly/go-simplejson v0.5.0 // indirect
 	github.com/cespare/xxhash/v2 v2.3.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.4 // indirect
 	github.com/cronokirby/saferith v0.33.0 // indirect
 	github.com/cstockton/go-conv v1.0.0 // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
@@ -174,6 +175,7 @@ require (
 	github.com/rickb777/plural v1.4.2 // indirect
 	github.com/rivo/uniseg v0.4.7 // indirect
 	github.com/rogpeppe/go-internal v1.12.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/sagikazarmark/locafero v0.6.0 // indirect
 	github.com/sourcegraph/conc v0.3.0 // indirect
 	github.com/spali/go-slicereader v0.0.0-20201122145524-8e262e1a5127 // indirect
diff --git a/go.sum b/go.sum
index 0089a62fb1..d49d126583 100644
--- a/go.sum
+++ b/go.sum
@@ -96,6 +96,7 @@ github.com/coreos/go-semver v0.2.0/go.mod h1:nnelYz7RCh+5ahJtPPxZlU+153eP4D4r3Ee
 github.com/coreos/go-systemd v0.0.0-20180511133405-39ca1b05acc7/go.mod h1:F5haX7vjVVG0kc13fIWeqUViNPyEJxv/OmvnBo0Yme4=
 github.com/coreos/pkg v0.0.0-20160727233714-3ac0863d7acf/go.mod h1:E3G3o1h8I7cfcXa63jLwjI0eiQQMgzzUDFVpN/nH/eA=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
+github.com/cpuguy83/go-md2man/v2 v2.0.4 h1:wfIWP927BUkWJb2NmU/kNDYIBTh/ziUX91+lVfRxZq4=
 github.com/cpuguy83/go-md2man/v2 v2.0.4/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/creack/pty v1.1.7/go.mod h1:lj5s0c3V2DBrqTV7llrYr5NG6My20zk30Fl46Y7DoTY=
 github.com/creack/pty v1.1.17 h1:QeVUsEDNrLBW4tMgZHvxy18sKtr6VI492kBhUfhDJNI=
@@ -577,6 +578,7 @@ github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFR
 github.com/rogpeppe/go-internal v1.12.0 h1:exVL4IDcn6na9z1rAb56Vxr+CgyK3nn3O+epU5NdKM8=
 github.com/rogpeppe/go-internal v1.12.0/go.mod h1:E+RYuTGaKKdloAfM02xzb0FW3Paa99yedzYV+kq4uf4=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
 github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/sagikazarmark/locafero v0.6.0 h1:ON7AQg37yzcRPU69mt7gwhFEBwxI6P9T4Qu3N51bwOk=