Update generation to include header and link handler

cmd/docs.go

@@ -1,13 +1,30 @@
 package cmd
 
 import (
+	"bytes"
+	"fmt"
+	"io"
 	"log"
 	"os"
+	"path"
+	"path/filepath"
+	"sort"
+	"strings"
+	"time"
 
 	"github.com/spf13/cobra"
-	"github.com/spf13/cobra/doc"
+	"golang.org/x/text/cases"
+	"golang.org/x/text/language"
 )
 
+var headerTemplate = `---
+id: %s
+slug: %s
+title: %s
+sidebar_label: %s
+---
+`
+
 func NewCmdDocs() *cobra.Command {
 	cmd := &cobra.Command{
 		Use:   "docs",
@@ -22,7 +39,7 @@ func NewCmdDocs() *cobra.Command {
 			if err != nil {
 				log.Fatal(err)
 			}
-			err = doc.GenMarkdownTree(rootCmd, dir)
+			err = GenMarkdownTreeCustom(rootCmd, dir, filePrepender, linkHandler)
 			if err != nil {
 				log.Fatal(err)
 			}
@@ -36,3 +53,156 @@ func NewCmdDocs() *cobra.Command {
 
 	return cmd
 }
+
+func filePrepender(filename string) string {
+	id := filepath.Base(filename)
+	base := strings.TrimSuffix(id, path.Ext(id))
+	slug := "/cli/commands/" + strings.ToLower(base)
+	title := cases.Title(language.AmericanEnglish).String(strings.ReplaceAll(base, "_", " "))
+
+	return fmt.Sprintf(headerTemplate, id, slug, title, title)
+}
+
+func linkHandler(filename string) string {
+	base := strings.TrimSuffix(filename, path.Ext(filename))
+	return "/cli/commands/" + base
+}
+
+// Currently cobra has a bug where there is an extra line added to the end of the md file when
+// the DisableAutoGenTag = true and this causes pre-commit to have to edit the file after generation
+// so the below section is copied from https://github.com/spf13/cobra/blob/v1.7.0/doc/md_docs.go#L55
+// with a fix to move the newline being added before the timestamp
+// https://github.com/spf13/cobra/issues/2029
+
+// GenMarkdownTreeCustom is the the same as GenMarkdownTree, but
+// with custom filePrepender and linkHandler.
+func GenMarkdownTreeCustom(cmd *cobra.Command, dir string, filePrepender, linkHandler func(string) string) error {
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
+			return err
+		}
+	}
+
+	basename := strings.ReplaceAll(cmd.CommandPath(), " ", "_") + ".md"
+	filename := filepath.Join(dir, basename)
+	f, err := os.Create(filename)
+	if err != nil {
+		return err
+	}
+	defer f.Close()
+
+	if _, err = io.WriteString(f, filePrepender(filename)); err != nil {
+		return err
+	}
+
+	return GenMarkdownCustom(cmd, f, linkHandler)
+}
+
+// GenMarkdownCustom creates custom markdown output.
+func GenMarkdownCustom(cmd *cobra.Command, w io.Writer, linkHandler func(string) string) error {
+	cmd.InitDefaultHelpCmd()
+	cmd.InitDefaultHelpFlag()
+
+	buf := new(bytes.Buffer)
+	name := cmd.CommandPath()
+
+	buf.WriteString("## " + name + "\n\n")
+	buf.WriteString(cmd.Short + "\n\n")
+	if len(cmd.Long) > 0 {
+		buf.WriteString("### Synopsis\n\n")
+		buf.WriteString(cmd.Long + "\n\n")
+	}
+
+	if cmd.Runnable() {
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.UseLine()))
+	}
+
+	if len(cmd.Example) > 0 {
+		buf.WriteString("### Examples\n\n")
+		buf.WriteString(fmt.Sprintf("```\n%s\n```\n\n", cmd.Example))
+	}
+
+	if err := printOptions(buf, cmd, name); err != nil {
+		return err
+	}
+	if hasSeeAlso(cmd) {
+		buf.WriteString("### SEE ALSO\n\n")
+		if cmd.HasParent() {
+			parent := cmd.Parent()
+			pname := parent.CommandPath()
+			link := pname + ".md"
+			link = strings.ReplaceAll(link, " ", "_")
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", pname, linkHandler(link), parent.Short))
+			cmd.VisitParents(func(c *cobra.Command) {
+				if c.DisableAutoGenTag {
+					cmd.DisableAutoGenTag = c.DisableAutoGenTag
+				}
+			})
+		}
+
+		children := cmd.Commands()
+		sort.Sort(byName(children))
+
+		for _, child := range children {
+			if !child.IsAvailableCommand() || child.IsAdditionalHelpTopicCommand() {
+				continue
+			}
+			cname := name + " " + child.Name()
+			link := cname + ".md"
+			link = strings.ReplaceAll(link, " ", "_")
+			buf.WriteString(fmt.Sprintf("* [%s](%s)\t - %s\n", cname, linkHandler(link), child.Short))
+		}
+	}
+	if !cmd.DisableAutoGenTag {
+		// This line was moved from inside the end of the hasSeeAlso block which stops it from adding
+		// an extra newline
+		buf.WriteString("\n")
+		buf.WriteString("###### Auto generated by spf13/cobra on " + time.Now().Format("2-Jan-2006") + "\n")
+	}
+	_, err := buf.WriteTo(w)
+	return err
+}
+
+// Test to see if we have a reason to print See Also information in docs
+// Basically this is a test for a parent command or a subcommand which is
+// both not deprecated and not the autogenerated help command.
+func hasSeeAlso(cmd *cobra.Command) bool {
+	if cmd.HasParent() {
+		return true
+	}
+	for _, c := range cmd.Commands() {
+		if !c.IsAvailableCommand() || c.IsAdditionalHelpTopicCommand() {
+			continue
+		}
+		return true
+	}
+	return false
+}
+
+func printOptions(buf *bytes.Buffer, cmd *cobra.Command, _ string) error {
+	flags := cmd.NonInheritedFlags()
+	flags.SetOutput(buf)
+	if flags.HasAvailableFlags() {
+		buf.WriteString("### Options\n\n```\n")
+		flags.PrintDefaults()
+		buf.WriteString("```\n\n")
+	}
+
+	parentFlags := cmd.InheritedFlags()
+	parentFlags.SetOutput(buf)
+	if parentFlags.HasAvailableFlags() {
+		buf.WriteString("### Options inherited from parent commands\n\n```\n")
+		parentFlags.PrintDefaults()
+		buf.WriteString("```\n\n")
+	}
+	return nil
+}
+
+type byName []*cobra.Command
+
+func (s byName) Len() int           { return len(s) }
+func (s byName) Swap(i, j int)      { s[i], s[j] = s[j], s[i] }
+func (s byName) Less(i, j int) bool { return s[i].Name() < s[j].Name() }

cmd/root.go

@@ -24,9 +24,10 @@ Configure and deploying infrastructure and applications.
 
 // rootCmd represents the base command when called without any subcommands
 var rootCmd = &cobra.Command{
-	Use:   "mass",
-	Short: "Massdriver Cloud CLI",
-	Long:  rootCmdHelp,
+	Use:               "mass",
+	Short:             "Massdriver Cloud CLI",
+	Long:              rootCmdHelp,
+	DisableAutoGenTag: true,
 }
 
 // Execute adds all child commands to the root command and sets flags appropriately.

docs/generated/mass.md

@@ -1,3 +1,9 @@
+---
+id: mass.md
+slug: /cli/commands/mass
+title: Mass
+sidebar_label: Mass
+---
 ## mass
 
 Massdriver Cloud CLI
@@ -26,16 +32,14 @@ Configure and deploying infrastructure and applications.
 
 ### SEE ALSO
 
-* [mass application](mass_application.md)	 - Manage applications
-* [mass artifact](mass_artifact.md)	 - Manage artifacts
-* [mass bundle](mass_bundle.md)	 - Generate and publish bundles
-* [mass completion](mass_completion.md)	 - Generate the autocompletion script for the specified shell
-* [mass docs](mass_docs.md)	 - Gen docs
-* [mass image](mass_image.md)	 - Container image integration Massdriver
-* [mass infrastructure](mass_infrastructure.md)	 - Manage infrastructure
-* [mass preview](mass_preview.md)	 - Create & deploy preview environments
-* [mass schema](mass_schema.md)	 - Manage JSON Schemas
-* [mass server](mass_server.md)	 - Start the bundle development server
-* [mass version](mass_version.md)	 - Version of Mass CLI
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass application](/cli/commands/mass_application)	 - Manage applications
+* [mass artifact](/cli/commands/mass_artifact)	 - Manage artifacts
+* [mass bundle](/cli/commands/mass_bundle)	 - Generate and publish bundles
+* [mass completion](/cli/commands/mass_completion)	 - Generate the autocompletion script for the specified shell
+* [mass docs](/cli/commands/mass_docs)	 - Gen docs
+* [mass image](/cli/commands/mass_image)	 - Container image integration Massdriver
+* [mass infrastructure](/cli/commands/mass_infrastructure)	 - Manage infrastructure
+* [mass preview](/cli/commands/mass_preview)	 - Create & deploy preview environments
+* [mass schema](/cli/commands/mass_schema)	 - Manage JSON Schemas
+* [mass server](/cli/commands/mass_server)	 - Start the bundle development server
+* [mass version](/cli/commands/mass_version)	 - Version of Mass CLI

docs/generated/mass_application.md

@@ -1,3 +1,9 @@
+---
+id: mass_application.md
+slug: /cli/commands/mass_application
+title: Mass Application
+sidebar_label: Mass Application
+---
 ## mass application
 
 Manage applications
@@ -15,9 +21,7 @@ Manage applications
 
 ### SEE ALSO
 
-* [mass](mass.md)	 - Massdriver Cloud CLI
-* [mass application configure](mass_application_configure.md)	 - Configure application
-* [mass application deploy](mass_application_deploy.md)	 - Deploy applications
-* [mass application patch](mass_application_patch.md)	 - Patch individual package parameter values
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass](/cli/commands/mass)	 - Massdriver Cloud CLI
+* [mass application configure](/cli/commands/mass_application_configure)	 - Configure application
+* [mass application deploy](/cli/commands/mass_application_deploy)	 - Deploy applications
+* [mass application patch](/cli/commands/mass_application_patch)	 - Patch individual package parameter values

docs/generated/mass_application_configure.md

@@ -1,3 +1,9 @@
+---
+id: mass_application_configure.md
+slug: /cli/commands/mass_application_configure
+title: Mass Application Configure
+sidebar_label: Mass Application Configure
+---
 ## mass application configure
 
 Configure application
@@ -48,6 +54,4 @@ mass application configure <project>-<target>-<manifest> [flags]
 
 ### SEE ALSO
 
-* [mass application](mass_application.md)	 - Manage applications
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass application](/cli/commands/mass_application)	 - Manage applications

docs/generated/mass_application_deploy.md

@@ -1,3 +1,9 @@
+---
+id: mass_application_deploy.md
+slug: /cli/commands/mass_application_deploy
+title: Mass Application Deploy
+sidebar_label: Mass Application Deploy
+---
 ## mass application deploy
 
 Deploy applications
@@ -45,6 +51,4 @@ mass application deploy <project>-<target>-<manifest> [flags]
 
 ### SEE ALSO
 
-* [mass application](mass_application.md)	 - Manage applications
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass application](/cli/commands/mass_application)	 - Manage applications

docs/generated/mass_application_patch.md

@@ -1,3 +1,9 @@
+---
+id: mass_application_patch.md
+slug: /cli/commands/mass_application_patch
+title: Mass Application Patch
+sidebar_label: Mass Application Patch
+---
 ## mass application patch
 
 Patch individual package parameter values
@@ -52,6 +58,4 @@ mass application patch <project>-<target>-<manifest> [flags]
 
 ### SEE ALSO
 
-* [mass application](mass_application.md)	 - Manage applications
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass application](/cli/commands/mass_application)	 - Manage applications

docs/generated/mass_artifact.md

@@ -1,3 +1,9 @@
+---
+id: mass_artifact.md
+slug: /cli/commands/mass_artifact
+title: Mass Artifact
+sidebar_label: Mass Artifact
+---
 ## mass artifact
 
 Manage artifacts
@@ -15,7 +21,5 @@ Manage artifacts
 
 ### SEE ALSO
 
-* [mass](mass.md)	 - Massdriver Cloud CLI
-* [mass artifact import](mass_artifact_import.md)	 - Import a custom artifact
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass](/cli/commands/mass)	 - Massdriver Cloud CLI
+* [mass artifact import](/cli/commands/mass_artifact_import)	 - Import a custom artifact

docs/generated/mass_artifact_import.md

@@ -1,3 +1,9 @@
+---
+id: mass_artifact_import.md
+slug: /cli/commands/mass_artifact_import
+title: Mass Artifact Import
+sidebar_label: Mass Artifact Import
+---
 ## mass artifact import
 
 Import a custom artifact
@@ -30,6 +36,4 @@ mass artifact import [flags]
 
 ### SEE ALSO
 
-* [mass artifact](mass_artifact.md)	 - Manage artifacts
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass artifact](/cli/commands/mass_artifact)	 - Manage artifacts

docs/generated/mass_bundle.md

@@ -1,3 +1,9 @@
+---
+id: mass_bundle.md
+slug: /cli/commands/mass_bundle
+title: Mass Bundle
+sidebar_label: Mass Bundle
+---
 ## mass bundle
 
 Generate and publish bundles
@@ -15,11 +21,9 @@ Generate and publish bundles
 
 ### SEE ALSO
 
-* [mass](mass.md)	 - Massdriver Cloud CLI
-* [mass bundle build](mass_bundle_build.md)	 - Build schemas from massdriver.yaml file
-* [mass bundle lint](mass_bundle_lint.md)	 - Check massdriver.yaml file for common errors
-* [mass bundle new](mass_bundle_new.md)	 - Create a new bundle from a template
-* [mass bundle publish](mass_bundle_publish.md)	 - Publish bundle to Massdriver's package manager
-* [mass bundle template](mass_bundle_template.md)	 - Application template development tools
-
-###### Auto generated by spf13/cobra on 19-Sep-2023
+* [mass](/cli/commands/mass)	 - Massdriver Cloud CLI
+* [mass bundle build](/cli/commands/mass_bundle_build)	 - Build schemas from massdriver.yaml file
+* [mass bundle lint](/cli/commands/mass_bundle_lint)	 - Check massdriver.yaml file for common errors
+* [mass bundle new](/cli/commands/mass_bundle_new)	 - Create a new bundle from a template
+* [mass bundle publish](/cli/commands/mass_bundle_publish)	 - Publish bundle to Massdriver's package manager
+* [mass bundle template](/cli/commands/mass_bundle_template)	 - Application template development tools