feat: add better markdown docs generation

pcli.go

@@ -22,8 +22,19 @@ func SetRootCmd(cmd *cobra.Command) {
 	rootPath = filepath.Join(scriptPath, "../../")
 }
 
-// generateMarkdown generates a help document written in markdown for a command.
 func generateMarkdown(cmd *cobra.Command) (md string) {
+	md += generateMarkdownTree(cmd)
+	md += "\n\n---\n"
+	md += "> **Documentation automatically generated with [PTerm](https://github.com/pterm/cli-template) on " + time.Now().Format("02 January 2006") + "**\n"
+
+	return
+}
+
+// generateMarkdownTree generates a help document written in markdown for a command.
+func generateMarkdownTree(cmd *cobra.Command) (md string) {
+	if cmd.Hidden {
+		return
+	}
 	pterm.DisableColor()
 	md += pterm.Sprintfln("# %s", cmd.CommandPath())
 	md += generateUsageTemplate(cmd)
@@ -60,20 +71,40 @@ func generateMarkdown(cmd *cobra.Command) (md string) {
 		for _, d := range flagTableData {
 			md += pterm.Sprintfln("|`%s`|%s|", d[0], d[1])
 		}
+	}
 
-		md += "---\n\n"
-		md += "###### Automatically generated with [PTerm](https://github.com/pterm/cli-template) on " + time.Now().Format("02 January 2006") + "\n"
+	for _, c := range cmd.Commands() {
+		md += generateMarkdownTree(c)
 	}
+
 	pterm.EnableColor()
 
 	return
 }
 
+// MarkdownDocument contains the command and it's markdown documentation.
+type MarkdownDocument struct {
+	Name     string
+	Markdown string
+	Command  *cobra.Command
+	Filename string
+}
+
 // GenerateMarkdownDocs walks trough every subcommand of rootCmd and creates a documentation written in Markdown for it.
-func GenerateMarkdownDocs(command *cobra.Command) (markdown []string) {
-	markdown = append(markdown, generateMarkdown(rootCmd))
+func GenerateMarkdownDocs(command *cobra.Command) (markdown []MarkdownDocument) {
+	markdown = append(markdown, MarkdownDocument{
+		Name:     command.Name(),
+		Markdown: generateMarkdown(rootCmd),
+		Command:  rootCmd,
+		Filename: strings.ReplaceAll(rootCmd.Name(), " ", "_"),
+	})
 	for _, cmd := range command.Commands() {
-		markdown = append(markdown, generateMarkdown(cmd))
+		markdown = append(markdown, MarkdownDocument{
+			Name:     cmd.Name(),
+			Markdown: generateMarkdown(cmd),
+			Command:  cmd,
+			Filename: strings.ReplaceAll(cmd.Name(), " ", "_"),
+		})
 		GenerateMarkdownDocs(cmd)
 	}
 	return

pterm-ci-cmd.go

@@ -29,8 +29,7 @@ It should not be used outside the development of this tool.`,
 		pterm.Fatal.PrintOnError(os.MkdirAll(getPathTo("/docs/commands"), 0777))
 
 		for _, doc := range markdownDocs {
-			docName := strings.ReplaceAll(strings.TrimSpace(strings.TrimLeft(strings.Split(doc, "\n")[0], "# ")), " ", "_")
-			pterm.Fatal.PrintOnError(ioutil.WriteFile(getPathTo(pterm.Sprintf("/docs/commands/%s.md", docName)), []byte(doc), 0777))
+			pterm.Fatal.PrintOnError(ioutil.WriteFile(getPathTo(pterm.Sprintf("/docs/commands/%s.md", doc.Name)), []byte(doc.Markdown), 0777))
 		}
 
 		project := struct {
@@ -112,7 +111,7 @@ func getPathTo(file string) string {
 	return filepath.Join("./", file)
 }
 
-func updateSidebar(docs []string) {
+func updateSidebar(docs []MarkdownDocument) {
 	sidebarPath := getPathTo("./docs/_sidebar.md")
 	sidebarContentByte, err := ioutil.ReadFile(sidebarPath)
 	pterm.Fatal.PrintOnError(err)
@@ -130,8 +129,7 @@ func updateSidebar(docs []string) {
 	newSidebarContent += before + "\n"
 
 	for _, doc := range docs {
-		docName := strings.ReplaceAll(strings.TrimSpace(strings.TrimLeft(strings.Split(doc, "\n")[0], "# ")), " ", "_")
-		newSidebarContent += "  - [" + docName + "](commands/" + docName + ".md)\n"
+		newSidebarContent += "  - [" + doc.Name + "](commands/" + doc.Filename + ".md)\n"
 	}
 
 	newSidebarContent += after