Merge remote-tracking branch 'origin/trunk' into cmd-reference-1734

vilmibm · vilmibm · commit 9d12dcf2decf · 2020-11-04T11:09:15.000-08: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,21 @@ 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() {
+		_, forceGeneration := c.Annotations["markdown:generate"]
+		if c.Hidden && !forceGeneration {
 			continue
 		}
+
 		if err := GenMarkdownTreeCustom(c, dir, filePrepender, linkHandler); err != nil {
 			return err
 		}
 	}
 
 	basename := strings.Replace(cmd.CommandPath(), " ", "_", -1) + ".md"
+	if basenameOverride, found := cmd.Annotations["markdown:basename"]; found {
+		basename = basenameOverride + ".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
@@ -45,10 +45,10 @@ func NewCmdCredits(f *cmdutil.Factory, runF func(*CreditsOptions) error) *cobra.
 		Example: heredoc.Doc(`
 			# see a credits animation for this project
 			$ gh credits
-			
+
 			# display a non-animated thank you
 			$ gh credits -s
-			
+
 			# just print the contributors, one per line
 			$ gh credits | cat
 		`),
diff --git a/pkg/cmd/root/help_topic.go b/pkg/cmd/root/help_topic.go
@@ -5,52 +5,60 @@ import (
 	"github.com/spf13/cobra"
 )
 
-func NewHelpTopic(topic string) *cobra.Command {
-	topicContent := make(map[string]string)
-
-	topicContent["environment"] = heredoc.Doc(`
-		GITHUB_TOKEN: an authentication token for github.com API requests. Setting this avoids
-		being prompted to authenticate and takes precedence over previously stored credentials.
+var HelpTopics = map[string]map[string]string{
+	"environment": {
+		"short": "Environment variables that can be used with gh",
+		"long": heredoc.Doc(`
+			GITHUB_TOKEN: an authentication token for github.com API requests. Setting this avoids
+			being prompted to authenticate and takes precedence over previously stored credentials.
 
-		GITHUB_ENTERPRISE_TOKEN: an authentication token for API requests to GitHub Enterprise.
+			GITHUB_ENTERPRISE_TOKEN: an authentication token for API requests to GitHub Enterprise.
 
-		GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands
-		that otherwise operate on a local repository.
+			GH_REPO: specify the GitHub repository in the "[HOST/]OWNER/REPO" format for commands
+			that otherwise operate on a local repository.
 
-		GH_HOST: specify the GitHub hostname for commands that would otherwise assume
-		the "github.com" host when not in a context of an existing repository.
+			GH_HOST: specify the GitHub hostname for commands that would otherwise assume
+			the "github.com" host when not in a context of an existing repository.
 
-		GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use
-		for authoring text.
+			GH_EDITOR, GIT_EDITOR, VISUAL, EDITOR (in order of precedence): the editor tool to use
+			for authoring text.
 
-		BROWSER: the web browser to use for opening links.
+			BROWSER: the web browser to use for opening links.
 
-		DEBUG: set to any value to enable verbose output to standard error. Include values "api"
-		or "oauth" to print detailed information about HTTP requests or authentication flow.
+			DEBUG: set to any value to enable verbose output to standard error. Include values "api"
+			or "oauth" to print detailed information about HTTP requests or authentication flow.
 
-		GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output to, e.g. "less".
+			GH_PAGER, PAGER (in order of precedence): a terminal paging program to send standard output to, e.g. "less".
 
-		GLAMOUR_STYLE: the style to use for rendering Markdown. See
-		https://github.com/charmbracelet/glamour#styles
+			GLAMOUR_STYLE: the style to use for rendering Markdown. See
+			https://github.com/charmbracelet/glamour#styles
 
-		NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.
+			NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.
 
-		CLICOLOR: set to "0" to disable printing ANSI colors in output.
+			CLICOLOR: set to "0" to disable printing ANSI colors in output.
 
-		CLICOLOR_FORCE: set to a value other than "0" to keep ANSI colors in output
-		even when the output is piped.
+			CLICOLOR_FORCE: set to a value other than "0" to keep ANSI colors in output
+			even when the output is piped.
 
-		GH_NO_UPDATE_NOTIFIER: set to any value to disable update notifications. By default, gh
-		checks for new releases once every 24 hours and displays an upgrade notice on standard
-		error if a newer version was found.
-	`)
+			GH_NO_UPDATE_NOTIFIER: set to any value to disable update notifications. By default, gh
+			checks for new releases once every 24 hours and displays an upgrade notice on standard
+			error if a newer version was found.
+		`),
+	},
+}
 
+func NewHelpTopic(topic string) *cobra.Command {
 	cmd := &cobra.Command{
 		Use:    topic,
-		Long:   topicContent[topic],
+		Short:  HelpTopics[topic]["short"],
+		Long:   HelpTopics[topic]["long"],
 		Hidden: true,
 		Args:   cobra.NoArgs,
 		Run:    helpTopicHelpFunc,
+		Annotations: map[string]string{
+			"markdown:generate": "true",
+			"markdown:basename": "gh_help_" + topic,
+		},
 	}
 
 	cmd.SetHelpFunc(helpTopicHelpFunc)
