Generate markdown for help topics

samcoe · samcoe · commit f770c6481c99 · 2020-11-04T12:35:58.000+03:00
diff --git a/cmd/gen-docs/main.go b/cmd/gen-docs/main.go
@@ -38,6 +38,7 @@ func main() {
 
 	io, _, _, _ := iostreams.Test()
 	rootCmd := root.NewCmdRoot(&cmdutil.Factory{IOStreams: io}, "", "")
+	rootCmd.InitDefaultHelpCmd()
 
 	err := os.MkdirAll(*dir, 0755)
 	if err != nil {
diff --git a/internal/docs/markdown.go b/internal/docs/markdown.go
@@ -82,15 +82,22 @@ func GenMarkdownTree(cmd *cobra.Command, dir string) error {
 // 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 genMarkdown, ok := c.Annotations["markdown:generate"]; ok {
+			if genMarkdown == "false" {
+				continue
+			}
 		}
+
 		if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
 			return err
 		}
 	}
 
 	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
+	if override, ok := cmd.Annotations["markdown:basename"]; ok {
+		basename = override + ".md"
+	}
+
 	filename := filepath.Join(dir, basename)
 	f, err := os.Create(filename)
 	if err != nil {
diff --git a/pkg/cmd/repo/credits/credits.go b/pkg/cmd/repo/credits/credits.go
@@ -61,6 +61,9 @@ func NewCmdCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *cobra.
 			return creditsRun(opts)
 		},
 		Hidden: true,
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	cmd.Flags().BoolVarP(&opts.Static, "static", "s", false, "Print a static version of the credits")
@@ -104,6 +107,9 @@ func NewCmdRepoCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *co
 			return creditsRun(opts)
 		},
 		Hidden: true,
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	cmd.Flags().BoolVarP(&opts.Static, "static", "s", false, "Print a static version of the credits")
diff --git a/pkg/cmd/repo/garden/garden.go b/pkg/cmd/repo/garden/garden.go
@@ -115,6 +115,9 @@ func NewCmdGarden(f *cmdutil.Factory, runF func(*GardenOptions) error) *cobra.Co
 			}
 			return gardenRun(&opts)
 		},
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	return cmd
diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go
@@ -55,6 +55,9 @@ func NewHelpTopic(topic string) *cobra.Command {
 		Hidden: true,
 		Args:   cobra.NoArgs,
 		Run:    helpTopicHelpFunc,
+		Annotations: map[string]string{
+			"markdown:basename": "gh_help_" + topic,
+		},
 	}
 
 	cmd.SetHelpFunc(helpTopicHelpFunc)
diff --git a/pkg/cmd/version/version.go b/pkg/cmd/version/version.go
@@ -16,6 +16,9 @@ func NewCmdVersion(f *cmdutil.Factory, version, buildDate string) *cobra.Command
 		Run: func(cmd *cobra.Command, args []string) {
 			fmt.Fprint(f.IOStreams.Out, Format(version, buildDate))
 		},
+		Annotations: map[string]string{
+			"markdown:generate": "false",
+		},
 	}
 
 	cmdutil.DisableAuthCheck(cmd)

Original file line number	Diff line number	Diff line change
`@@ -115,6 +115,9 @@ func NewCmdGarden(f cmdutil.Factory, runF func(GardenOptions) error) *cobra.Co`
`115`	`115`	`}`
`116`	`116`	`return gardenRun(&opts)`
`117`	`117`	`},`
	`118`	`+ Annotations: map[string]string{`
	`119`	`+ "markdown:generate": "false",`
	`120`	`+ },`
`118`	`121`	`}`
`119`	`122`
`120`	`123`	`return cmd`
Original file line number	Diff line number	Diff line change
`@@ -55,6 +55,9 @@ func NewHelpTopic(topic string) *cobra.Command {`
`55`	`55`	`Hidden: true,`
`56`	`56`	`Args: cobra.NoArgs,`
`57`	`57`	`Run: helpTopicHelpFunc,`
	`58`	`+ Annotations: map[string]string{`
	`59`	`+ "markdown:basename": "gh_help_" + topic,`
	`60`	`+ },`
`58`	`61`	`}`
`59`	`62`
`60`	`63`	`cmd.SetHelpFunc(helpTopicHelpFunc)`
Original file line number	Diff line number	Diff line change
`@@ -16,6 +16,9 @@ func NewCmdVersion(f cmdutil.Factory, version, buildDate string) cobra.Command`
`16`	`16`	`Run: func(cmd *cobra.Command, args []string) {`
`17`	`17`	`fmt.Fprint(f.IOStreams.Out, Format(version, buildDate))`
`18`	`18`	`},`
	`19`	`+ Annotations: map[string]string{`
	`20`	`+ "markdown:generate": "false",`
	`21`	`+ },`
`19`	`22`	`}`
`20`	`23`
`21`	`24`	`cmdutil.DisableAuthCheck(cmd)`