Merge pull request #4675 from cli/docs-web-formatting

Overhaul manual pages for the web

pkg/cmd/actions/actions.go

@@ -1,8 +1,6 @@
 package actions
 
 import (
-	"fmt"
-
 	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/pkg/cmdutil"
 	"github.com/cli/cli/v2/pkg/iostreams"
@@ -14,11 +12,8 @@ func NewCmdActions(f *cmdutil.Factory) *cobra.Command {
 
 	cmd := &cobra.Command{
 		Use:   "actions",
-		Short: "Learn about working with GitHub actions",
+		Short: "Learn about working with GitHub Actions",
 		Long:  actionsExplainer(cs),
-		Run: func(cmd *cobra.Command, args []string) {
-			fmt.Fprintln(f.IOStreams.Out, actionsExplainer(cs))
-		},
 		Annotations: map[string]string{
 			"IsActions": "true",
 		},

pkg/cmd/codespace/ssh.go

@@ -12,6 +12,7 @@ import (
 	"path/filepath"
 	"strings"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/internal/codespaces"
 	"github.com/cli/cli/v2/pkg/cmdutil"
 	"github.com/cli/cli/v2/pkg/liveshare"
@@ -156,36 +157,36 @@ func newCpCmd(app *App) *cobra.Command {
 	var opts cpOptions
 
 	cpCmd := &cobra.Command{
-		Use:   "cp [-e] [-r] srcs... dest",
+		Use:   "cp [-e] [-r] <sources>... <dest>",
 		Short: "Copy files between local and remote file systems",
-		Long: `
-The cp command copies files between the local and remote file systems.
+		Long: heredoc.Docf(`
+			The cp command copies files between the local and remote file systems.
 
-As with the UNIX cp command, the first argument specifies the source and the last
-specifies the destination; additional sources may be specified after the first,
-if the destination is a directory.
+			As with the UNIX %[1]scp%[1]s command, the first argument specifies the source and the last
+			specifies the destination; additional sources may be specified after the first,
+			if the destination is a directory.
 
-The -r (recursive) flag is required if any source is a directory.
+			The %[1]s--recursive%[1]s flag is required if any source is a directory.
 
-A 'remote:' prefix on any file name argument indicates that it refers to
-the file system of the remote (Codespace) machine. It is resolved relative
-to the home directory of the remote user.
+			A "remote:" prefix on any file name argument indicates that it refers to
+			the file system of the remote (Codespace) machine. It is resolved relative
+			to the home directory of the remote user.
 
-By default, remote file names are interpreted literally. With the -e flag,
-each such argument is treated in the manner of scp, as a Bash expression to
-be evaluated on the remote machine, subject to expansion of tildes, braces,
-globs, environment variables, and backticks, as in these examples:
-
- $ gh codespace cp -e README.md 'remote:/workspace/$RepositoryName/'
- $ gh codespace cp -e 'remote:~/*.go' ./gofiles/
- $ gh codespace cp -e 'remote:/workspace/myproj/go.{mod,sum}' ./gofiles/
-
-For security, do not use the -e flag with arguments provided by untrusted
-users; see https://lwn.net/Articles/835962/ for discussion.
-`,
+			By default, remote file names are interpreted literally. With the %[1]s--expand%[1]s flag,
+			each such argument is treated in the manner of %[1]sscp%[1]s, as a Bash expression to
+			be evaluated on the remote machine, subject to expansion of tildes, braces, globs,
+			environment variables, and backticks. For security, do not use this flag with arguments
+			provided by untrusted users; see <https://lwn.net/Articles/835962/> for discussion.
+		`, "`"),
+		Example: heredoc.Doc(`
+			$ gh codespace cp -e README.md 'remote:/workspace/$RepositoryName/'
+			$ gh codespace cp -e 'remote:~/*.go' ./gofiles/
+			$ gh codespace cp -e 'remote:/workspace/myproj/go.{mod,sum}' ./gofiles/
+		`),
 		RunE: func(cmd *cobra.Command, args []string) error {
 			return app.Copy(cmd.Context(), args, opts)
 		},
+		DisableFlagsInUseLine: true,
 	}
 
 	// We don't expose all sshOptions.

pkg/cmd/root/help_topic.go

@@ -54,7 +54,7 @@ var HelpTopics = map[string]map[string]string{
 			to, e.g. "less".
 
 			GLAMOUR_STYLE: the style to use for rendering Markdown. See
-			https://github.com/charmbracelet/glamour#styles
+			<https://github.com/charmbracelet/glamour#styles>
 
 			NO_COLOR: set to any value to avoid printing ANSI escape sequences for color output.
 
@@ -90,14 +90,14 @@ var HelpTopics = map[string]map[string]string{
 			The %[1]s--jq%[1]s option accepts a query in jq syntax and will print only the resulting
 			values that match the query. This is equivalent to piping the output to %[1]sjq -r%[1]s,
 			but does not require the jq utility to be installed on the system. To learn more
-			about the query syntax, see: https://stedolan.github.io/jq/manual/v1.6/
+			about the query syntax, see: <https://stedolan.github.io/jq/manual/v1.6/>
 
 			With %[1]s--template%[1]s, the provided Go template is rendered using the JSON data as input.
-			For the syntax of Go templates, see: https://golang.org/pkg/text/template/
+			For the syntax of Go templates, see: <https://golang.org/pkg/text/template/>
 
 			The following functions are available in templates:
 			- %[1]sautocolor%[1]s: like %[1]scolor%[1]s, but only emits color to terminals
-			- %[1]scolor <style> <input>%[1]s: colorize input using https://github.com/mgutz/ansi
+			- %[1]scolor <style> <input>%[1]s: colorize input using <https://github.com/mgutz/ansi>
 			- %[1]sjoin <sep> <list>%[1]s: joins values in the list using a separator
 			- %[1]spluck <field> <list>%[1]s: collects values of a field from all items in the input
 			- %[1]stablerow <fields>...%[1]s: aligns fields in output vertically as a table

pkg/cmd/secret/secret.go

@@ -16,7 +16,10 @@ func NewCmdSecret(f *cmdutil.Factory) *cobra.Command {
 		Long: heredoc.Doc(`
 			Secrets can be set at the repository, environment, or organization level for use in
 			GitHub Actions. Run "gh help secret set" to learn how to get started.
-`),
+		`),
+		Annotations: map[string]string{
+			"IsActions": "true",
+		},
 	}
 
 	cmdutil.EnableRepoOverride(cmd, f)