Merge pull request #14 from mdb/update-command-docs

Author: mdb

Makefile

@@ -1,6 +1,6 @@
 SOURCE=./...
 GOFMT_FILES?=$$(find . -type f -name '*.go')
-VERSION?=0.0.1
+VERSION?=0.0.2
 
 default: build
 

cmd/repository.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net/http"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/pkg/cmd/workflow/shared"
 	"github.com/cli/cli/v2/pkg/iostreams"
 	"github.com/cli/go-gh"
@@ -33,10 +34,30 @@ var (
 
 // repositoryCmd represents the repository subcommand
 var repositoryCmd = &cobra.Command{
-	Use:     "repository",
-	Short:   `The 'repository' subcommand triggers repository dispatch events`,
-	Long:    `The 'repository' subcommand triggers repository dispatch events`,
-	Example: `TODO`,
+	Use: heredoc.Doc(`
+		repository \
+			--repo [owner/repo] \
+			--event-type [event-type] \
+			--client-payload [json-string] \
+			--workflow [workflow-name]
+	`),
+	Short: "Send a repository dispatch event and watch the resulting GitHub Actions run",
+	Long: heredoc.Doc(`
+		This command sends a repository dispatch event and attempts to find and watch the
+		resulting GitHub Actions run whose name is specified as '--workflow'.
+
+		Note that the command assumes the specified workflow supports a repository_dispatch
+		'on' trigger. Also note that the command is vulnerable to race conditions and may
+		watch an unrelated GitHub Actions workflow run in the event that multiple runs of
+		the specified workflow are running concurrently.
+	`),
+	Example: heredoc.Doc(`
+		gh dispatch repository \
+			--repo mdb/gh-dispatch \
+			--event-type 'hello' \
+			--client-payload '{"name": "Mike"}' \
+			--workflow Hello
+	`),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		repo, _ := cmd.Flags().GetString("repo")
 

cmd/root.go

@@ -3,15 +3,18 @@ package cmd
 import (
 	"os"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/spf13/cobra"
 )
 
 // rootCmd is the root command.
 var rootCmd = &cobra.Command{
-	Use:          "gh dispatch",
-	Short:        "gh dispatch: Trigger a GitHub dispatch event and watch the resulting GitHub Actions run",
-	Long:         "gh dispatch: Trigger a GitHub dispatch event and watch the resulting GitHub Actions run",
-	Example:      "TODO",
+	Use:   "gh dispatch",
+	Short: "Send a GitHub dispatch event and watch the resulting GitHub Actions run",
+	Long: heredoc.Doc(`
+		Send a workflow_dispatch or repository_dispatch event and watch the resulting
+		GitHub Actions run.
+	`),
 	SilenceUsage: true,
 }
 

cmd/workflow.go

@@ -6,6 +6,7 @@ import (
 	"fmt"
 	"net/http"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/cli/cli/v2/pkg/cmd/workflow/shared"
 	"github.com/cli/cli/v2/pkg/iostreams"
 	"github.com/cli/go-gh"
@@ -32,14 +33,36 @@ var (
 )
 
 // workflowCmd represents the workflow subcommand
-// TODO: it appears the resulting run rendering may
-// sometimes fail to denote each job as passing or failing,
-// perhaps due to a race condition somewhere?
 var workflowCmd = &cobra.Command{
-	Use:     "workflow",
-	Short:   `The 'workflow' subcommand triggers workflow dispatch events`,
-	Long:    `The 'workflow' subcommand triggers workflow dispatch events`,
-	Example: `TODO`,
+	Use: heredoc.Doc(`
+		workflow \
+			--repo [owner/repo] \
+			--inputs [json-string] \
+			--workflow [workflow-file-name.yaml]
+	`),
+	Short: "Send a workflow dispatch event and watch the resulting GitHub Actions run",
+	Long: heredoc.Doc(`
+		This command sends a workflow dispatch event and attempts to find and watch the
+		resulting GitHub Actions run whose file name or ID is specified as '--workflow'.
+
+		Note that the command assumes the specified workflow supports a workflow_dispatch
+		'on' trigger. Also note that the command is vulnerable to race conditions and may
+		watch an unrelated GitHub Actions workflow run in the event that multiple runs of
+		the specified workflow are running concurrently.
+	`),
+	Example: heredoc.Doc(`
+		gh dispatch workflow \
+			--repo mdb/gh-dispatch \
+			--inputs '{"name": "Mike"}' \
+			--workflow workflow_dispatch.yaml
+
+		# Specify a workflow ref other than 'main'
+		gh dispatch workflow \
+			--repo mdb/gh-dispatch \
+			--inputs '{"name": "Mike"}' \
+			--workflow workflow_dispatch.yaml \
+			--ref my-feature-branch
+	`),
 	RunE: func(cmd *cobra.Command, args []string) error {
 		repo, _ := cmd.Flags().GetString("repo")
 

go.mod

@@ -3,6 +3,7 @@ module github.com/mdb/gh-dispatch
 go 1.19
 
 require (
+	github.com/MakeNowJust/heredoc v1.0.0
 	github.com/cli/cli/v2 v2.18.1
 	github.com/cli/go-gh v0.1.2
 	github.com/spf13/cobra v1.6.0

go.sum

@@ -1,6 +1,7 @@
 github.com/AlecAivazis/survey/v2 v2.3.6 h1:NvTuVHISgTHEHeBFqt6BHOe4Ny/NwGZr7w+F8S9ziyw=
 github.com/AlecAivazis/survey/v2 v2.3.6/go.mod h1:4AuI9b7RjAR+G7v9+C4YSlX/YL3K3cWNXgWXOhllqvI=
 github.com/MakeNowJust/heredoc v1.0.0 h1:cXCdzVdstXyiTqTvfqk9SDHpKNjxuom+DOlyEeQ4pzQ=
+github.com/MakeNowJust/heredoc v1.0.0/go.mod h1:mG5amYoWBHf8vpLOuehzbGGw0EHxpZZ6lCpQ4fNJ8LE=
 github.com/Netflix/go-expect v0.0.0-20220104043353-73e0943537d2 h1:+vx7roKuyA63nhn5WAunQHLTznkw5W8b1Xc0dNjp83s=
 github.com/Netflix/go-expect v0.0.0-20220104043353-73e0943537d2/go.mod h1:HBCaDeC1lPdgDeDbhX8XFpy1jqjK0IBG8W5K+xYqA0w=
 github.com/briandowns/spinner v1.18.1 h1:yhQmQtM1zsqFsouh09Bk/jCjd50pC3EOGsh28gLVvwY=

main_test.go

@@ -11,6 +11,7 @@ import (
 	"testing"
 	"time"
 
+	"github.com/MakeNowJust/heredoc"
 	"github.com/stretchr/testify/assert"
 )
 
@@ -26,7 +27,25 @@ func TestMain(m *testing.M) {
 }
 
 func TestRootAcceptance(t *testing.T) {
-	basicOut := "gh dispatch: Trigger a GitHub dispatch event and watch the resulting GitHub Actions run\n\nUsage:\n  gh [command]\n\nExamples:\nTODO\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  help        Help about any command\n  repository  The 'repository' subcommand triggers repository dispatch events\n  workflow    The 'workflow' subcommand triggers workflow dispatch events\n\nFlags:\n  -h, --help          help for gh\n  -R, --repo string   The targeted repository's full name (in 'owner/repo' format)\n  -v, --version       version for gh\n\nUse \"gh [command] --help\" for more information about a command.\n"
+	basicOut := heredoc.Doc(`Send a workflow_dispatch or repository_dispatch event and watch the resulting
+GitHub Actions run.
+
+Usage:
+  gh [command]
+
+Available Commands:
+  completion  Generate the autocompletion script for the specified shell
+  help        Help about any command
+  repository  Send a repository dispatch event and watch the resulting GitHub Actions run
+  workflow    Send a workflow dispatch event and watch the resulting GitHub Actions run
+
+Flags:
+  -h, --help          help for gh
+  -R, --repo string   The targeted repository's full name (in 'owner/repo' format)
+  -v, --version       version for gh
+
+Use "gh [command] --help" for more information about a command.
+`)
 	tests := []struct {
 		args    []string
 		wantOut string