Merge pull request cli#1167 from cli/doc-examples-tweaks

Fix doc EXAMPLES formatting for HTML

command/alias.go

@@ -5,6 +5,7 @@ import (
 	"sort"
 	"strings"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/utils"
 	"github.com/google/shlex"
 	"github.com/spf13/cobra"
@@ -23,24 +24,30 @@ var aliasCmd = &cobra.Command{
 }
 
 var aliasSetCmd = &cobra.Command{
-	Use: "set <alias> <expansion>",
+	Use:   "set <alias> <expansion>",
+	Short: "Create a shortcut for a gh command",
+	Long: `Declare a word as a command alias that will expand to the specified command.
+
+The expansion may specify additional arguments and flags. If the expansion
+includes positional placeholders such as '$1', '$2', etc., any extra arguments
+that follow the invocation of an alias will be inserted appropriately.`,
+	Example: heredoc.Doc(`
+	$ gh alias set pv 'pr view'
+	$ gh pv -w 123
+	#=> gh pr view -w 123
+	
+	$ gh alias set bugs 'issue list --label="bugs"'
+
+	$ gh alias set epicsBy 'issue list --author="$1" --label="epic"'
+	$ gh epicsBy vilmibm
+	#=> gh issue list --author="vilmibm" --label="epic"
+	`),
+	Args: cobra.MinimumNArgs(2),
+	RunE: aliasSet,
+
 	// NB: this allows a user to eschew quotes when specifiying an alias expansion. We'll have to
 	// revisit it if we ever want to add flags to alias set but we have no current plans for that.
 	DisableFlagParsing: true,
-	Short:              "Create a shortcut for a gh command",
-	Long:               `This command lets you write your own shortcuts for running gh. They can be simple strings or accept placeholder arguments.`,
-	Example: `
-	gh alias set pv 'pr view'
-	# gh pv -w 123 -> gh pr view -w 123.
-
-	gh alias set bugs 'issue list --label="bugs"'
-	# gh bugs -> gh issue list --label="bugs".
-
-	gh alias set epicsBy 'issue list --author="$1" --label="epic"'
-	# gh epicsBy vilmibm -> gh issue list --author="$1" --label="epic"
-`,
-	Args: cobra.MinimumNArgs(2),
-	RunE: aliasSet,
 }
 
 func aliasSet(cmd *cobra.Command, args []string) error {
@@ -168,11 +175,10 @@ func aliasList(cmd *cobra.Command, args []string) error {
 }
 
 var aliasDeleteCmd = &cobra.Command{
-	Use:     "delete <alias>",
-	Short:   "Delete an alias.",
-	Args:    cobra.ExactArgs(1),
-	Example: "gh alias delete co",
-	RunE:    aliasDelete,
+	Use:   "delete <alias>",
+	Short: "Delete an alias.",
+	Args:  cobra.ExactArgs(1),
+	RunE:  aliasDelete,
 }
 
 func aliasDelete(cmd *cobra.Command, args []string) error {

command/config.go

@@ -3,6 +3,7 @@ package command
 import (
 	"fmt"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/spf13/cobra"
 )
 
@@ -34,20 +35,20 @@ Current respected settings:
 var configGetCmd = &cobra.Command{
 	Use:   "get <key>",
 	Short: "Print the value of a given configuration key",
-	Example: `
+	Example: heredoc.Doc(`
 	$ gh config get git_protocol
 	https
-`,
+	`),
 	Args: cobra.ExactArgs(1),
 	RunE: configGet,
 }
 
 var configSetCmd = &cobra.Command{
 	Use:   "set <key> <value>",
 	Short: "Update configuration with a value for the given key",
-	Example: `
+	Example: heredoc.Doc(`
 	$ gh config set editor vim
-`,
+	`),
 	Args: cobra.ExactArgs(2),
 	RunE: configSet,
 }

command/credits.go

@@ -11,6 +11,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/spf13/cobra"
 	"golang.org/x/crypto/ssh/terminal"
 
@@ -44,11 +45,16 @@ var creditsCmd = &cobra.Command{
 	Use:   "credits",
 	Short: "View credits for this tool",
 	Long:  `View animated credits for gh, the tool you are currently using :)`,
-	Example: `gh credits            # see a credits animation for this project
-  gh credits owner/repo # see a credits animation for owner/repo
-  gh credits -s         # display a non-animated thank you
-  gh credits | cat      # just print the contributors, one per line
-`,
+	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
+	`),
 	Args:   cobra.ExactArgs(0),
 	RunE:   ghCredits,
 	Hidden: true,

command/gist.go

@@ -8,6 +8,7 @@ import (
 	"os"
 	"path"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/api"
 	"github.com/cli/cli/utils"
 	"github.com/spf13/cobra"
@@ -27,21 +28,30 @@ var gistCmd = &cobra.Command{
 }
 
 var gistCreateCmd = &cobra.Command{
-	Use:   `create {<filename>|-}...`,
+	Use:   `create [<filename>... | -]`,
 	Short: "Create a new gist",
-	Long: `gh gist create: create gists
-
-Gists can be created from one or many files. This command can also read from STDIN. By default, gists are private; use --public to change this.
-
-Examples
-
-    gh gist create hello.py                   # turn file hello.py into a gist
-    gh gist create --public hello.py          # turn file hello.py into a public gist
-    gh gist create -d"a file!" hello.py       # turn file hello.py into a gist, with description
-    gh gist create hello.py world.py cool.txt # make a gist out of several files
-    gh gist create -                          # read from STDIN to create a gist
-    cat cool.txt | gh gist create             # read the output of another command and make a gist out of it
-`,
+	Long: `Create a new GitHub gist with given contents.
+
+Gists can be created from one or multiple files. Alternatively, pass "-" as
+file name to read from standard input.
+
+By default, gists are private; use '--public' to make publicly listed ones.`,
+	Example: heredoc.Doc(`
+	# publish file 'hello.py' as a public gist
+	$ gh gist create --public hello.py
+	
+	# create a gist with a description
+	$ gh gist create hello.py -d "my Hello-World program in Python"
+
+	# create a gist containing several files
+	$ gh gist create hello.py world.py cool.txt
+	
+	# read from standard input to create a gist
+	$ gh gist create -
+	
+	# create a gist from output piped from another command
+	$ cat cool.txt | gh gist create
+	`),
 	RunE: gistCreate,
 }
 

command/help.go

@@ -2,6 +2,7 @@ package command
 
 import (
 	"fmt"
+	"regexp"
 	"strings"
 
 	"github.com/cli/cli/utils"
@@ -78,8 +79,11 @@ func rootHelpFunc(command *cobra.Command, args []string) {
 	if len(additionalCommands) > 0 {
 		helpEntries = append(helpEntries, helpEntry{"ADDITIONAL COMMANDS", strings.Join(additionalCommands, "\n")})
 	}
-	if command.HasLocalFlags() {
-		helpEntries = append(helpEntries, helpEntry{"FLAGS", strings.TrimRight(command.LocalFlags().FlagUsages(), "\n")})
+
+	flagUsages := command.LocalFlags().FlagUsages()
+	if flagUsages != "" {
+		dedent := regexp.MustCompile(`(?m)^  `)
+		helpEntries = append(helpEntries, helpEntry{"FLAGS", dedent.ReplaceAllString(flagUsages, "")})
 	}
 	if _, ok := command.Annotations["help:arguments"]; ok {
 		helpEntries = append(helpEntries, helpEntry{"ARGUMENTS", command.Annotations["help:arguments"]})
@@ -101,7 +105,6 @@ Read the manual at http://cli.github.com/manual`})
 			fmt.Fprintln(out, utils.Bold(e.Title))
 
 			for _, l := range strings.Split(strings.Trim(e.Body, "\n\r"), "\n") {
-				l = strings.Trim(l, " \n\r")
 				fmt.Fprintln(out, "  "+l)
 			}
 		} else {

command/issue.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/api"
 	"github.com/cli/cli/git"
 	"github.com/cli/cli/internal/ghrepo"
@@ -52,9 +53,11 @@ var issueCmd = &cobra.Command{
 	Use:   "issue <command>",
 	Short: "Create and view issues",
 	Long:  `Work with GitHub issues`,
-	Example: `$ gh issue list
-$ gh issue create --fill
-$ gh issue view --web`,
+	Example: heredoc.Doc(`
+	$ gh issue list
+	$ gh issue create --label bug
+	$ gh issue view --web
+	`),
 	Annotations: map[string]string{
 		"IsCore": "true",
 		"help:arguments": `An issue can be supplied as argument in any of the following formats:

command/pr.go

@@ -10,6 +10,7 @@ import (
 	"strings"
 
 	"github.com/AlecAivazis/survey/v2"
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/api"
 	"github.com/cli/cli/context"
 	"github.com/cli/cli/git"
@@ -49,10 +50,11 @@ var prCmd = &cobra.Command{
 	Use:   "pr <command>",
 	Short: "Create, view, and checkout pull requests",
 	Long:  `Work with GitHub pull requests`,
-	Example: `$ gh pr checkout 353
-$ gh pr checkout bug-fix-branch
-$ gh pr create --fill
-$ gh pr view --web`,
+	Example: heredoc.Doc(`
+	$ gh pr checkout 353
+	$ gh pr create --fill
+	$ gh pr view --web
+	`),
 	Annotations: map[string]string{
 		"IsCore": "true",
 		"help:arguments": `A pull request can be supplied as argument in any of the following formats:
@@ -63,9 +65,11 @@ $ gh pr view --web`,
 var prListCmd = &cobra.Command{
 	Use:   "list",
 	Short: "List and filter pull requests in this repository",
-	Example: `$ gh pr list --limit all
-$ gh pr list --state closed
-$ gh pr list --label “priority 1” “bug”`,
+	Example: heredoc.Doc(`
+	$ gh pr list --limit 999
+	$ gh pr list --state closed
+	$ gh pr list --label "priority 1" --label "bug"
+	`),
 	RunE: prList,
 }
 var prStatusCmd = &cobra.Command{

command/pr_review.go

@@ -5,6 +5,7 @@ import (
 	"fmt"
 
 	"github.com/AlecAivazis/survey/v2"
+	"github.com/MakeNowJust/heredoc"
 	"github.com/spf13/cobra"
 
 	"github.com/cli/cli/api"
@@ -23,18 +24,24 @@ func init() {
 
 var prReviewCmd = &cobra.Command{
 	Use:   "review [<number> | <url> | <branch>]",
-	Short: "Add a review to a pull request.",
-	Args:  cobra.MaximumNArgs(1),
-	Long: `Add a review to either a specified pull request or the pull request associated with the current branch.
-
-Examples:
-
-	gh pr review                                  # add a review for the current branch's pull request
-	gh pr review 123                              # add a review for pull request 123
-	gh pr review -a                               # mark the current branch's pull request as approved
-	gh pr review -c -b "interesting"              # comment on the current branch's pull request
-	gh pr review 123 -r -b "needs more ascii art" # request changes on pull request 123
-	`,
+	Short: "Add a review to a pull request",
+	Long: `Add a review to a pull request.
+
+Without an argument, the pull request that belongs to the current branch is reviewed.`,
+	Example: heredoc.Doc(`
+	# approve the pull request of the current branch
+	$ gh pr review --approve
+	
+	# leave a review comment for the current branch
+	$ gh pr review --comment -b "interesting"
+	
+	# add a review for a specific pull request
+	$ gh pr review 123
+	
+	# request changes on a specific pull request
+	$ gh pr review 123 -r -b "needs more ASCII art"
+	`),
+	Args: cobra.MaximumNArgs(1),
 	RunE: prReview,
 }
 

command/repo.go

@@ -10,6 +10,7 @@ import (
 	"time"
 
 	"github.com/AlecAivazis/survey/v2"
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/api"
 	"github.com/cli/cli/git"
 	"github.com/cli/cli/internal/ghrepo"
@@ -47,10 +48,11 @@ var repoCmd = &cobra.Command{
 	Use:   "repo <command>",
 	Short: "Create, clone, fork, and view repositories",
 	Long:  `Work with GitHub repositories`,
-	Example: `$ gh repo create
-$ gh repo clone cli/cli 
-$ gh repo view --web
-`,
+	Example: heredoc.Doc(`
+	$ gh repo create
+	$ gh repo clone cli/cli
+	$ gh repo view --web
+	`),
 	Annotations: map[string]string{
 		"IsCore": "true",
 		"help:arguments": `
@@ -75,15 +77,17 @@ To pass 'git clone' flags, separate them with '--'.`,
 var repoCreateCmd = &cobra.Command{
 	Use:   "create [<name>]",
 	Short: "Create a new repository",
-	Long:  `Create a new GitHub repository`,
-	Example: utils.Bold("$ gh repo create") + `
-Will create a repository on your account using the name of your current directory
+	Long:  `Create a new GitHub repository.`,
+	Example: heredoc.Doc(`
+	# create a repository under your account using the current directory name
+	$ gh repo create
 
-` + utils.Bold("$ gh repo create my-project") + `
-Will create a repository on your account using the name 'my-project'
+	# create a repository with a specific name
+	$ gh repo create my-project
 
-` + utils.Bold("$ gh repo create cli/my-project") + `
-Will create a repository in the organization 'cli' using the name 'my-project'`,
+	# create a repository in an organization
+	$ gh repo create cli/my-project
+	`),
 	Annotations: map[string]string{"help:arguments": `A repository can be supplied as an argument in any of the following formats:
 - <OWNER/REPO>
 - by URL, e.g. "https://github.com/OWNER/REPO"`},
@@ -113,11 +117,19 @@ With '--web', open the repository in a web browser instead.`,
 var repoCreditsCmd = &cobra.Command{
 	Use:   "credits [<repository>]",
 	Short: "View credits for a repository",
-	Example: `$ gh repo credits           # view credits for the current repository
-$ gh repo credits cool/repo # view credits for cool/repo
-$ gh repo credits -s        # print a non-animated thank you
-$ gh repo credits | cat     # pipe to just print the contributors, one per line
-`,
+	Example: heredoc.Doc(`
+	# view credits for the current repository
+	$ gh repo credits
+	
+	# view credits for a specific repository
+	$ gh repo credits cool/repo
+
+	# print a non-animated thank you
+	$ gh repo credits -s
+	
+	# pipe to just print the contributors, one per line
+	$ gh repo credits | cat
+	`),
 	Args:   cobra.MaximumNArgs(1),
 	RunE:   repoCredits,
 	Hidden: true,