Merge pull request #717 from zampierilucas/documentation_examples

Added documentation examples on every command; Fixes

cmd/ci_artifacts.go

@@ -22,13 +22,11 @@ var ciArtifactsCmd = &cobra.Command{
 		The branch name, when using with the --merge-request option, can be the
 		merge request number, which matches the branch name internally.	The "job"
 		portion is the given job name, which may contain whitespace characters
-		and which, for this specific case, must be quoted.
-	`),
+		and which, for this specific case, must be quoted.`),
 	Example: heredoc.Doc(`
 		lab ci artifacts upstream feature_branch
 		lab ci artifacts upstream 125 --merge-request
-		lab ci artifacts upstream 125:'my custom stage' --merge-request
-	`),
+		lab ci artifacts upstream 125:'my custom stage' --merge-request`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		var (

cmd/ci_lint.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"fmt"
+	"github.com/MakeNowJust/heredoc/v2"
 	"io/ioutil"
 	"os"
 
@@ -13,8 +14,11 @@ import (
 
 // ciLintCmd represents the lint command
 var ciLintCmd = &cobra.Command{
-	Use:              "lint",
-	Short:            "Validate .gitlab-ci.yml against GitLab",
+	Use:   "lint",
+	Short: "Validate .gitlab-ci.yml against GitLab",
+	Example: heredoc.Doc(`
+		lab ci lint
+		lab ci lint upstream`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		path := ".gitlab-ci.yml"

cmd/ci_run.go

@@ -27,12 +27,10 @@ var ciCreateCmd = &cobra.Command{
 		Project will be inferred from branch if not provided
 
 		Note: "lab ci create" differs from "lab ci trigger" which is a
-		different API
-	`),
+		different API`),
 	Example: heredoc.Doc(`
 		lab ci create feature_branch
-		lab ci create -p engineering/integration_tests master
-	`),
+		lab ci create -p engineering/integration_tests master`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		pid, branch, err := getCIRunOptions(cmd, args)
@@ -60,13 +58,11 @@ var ciTriggerCmd = &cobra.Command{
 
 		Project will be inferred from branch if not provided
 
-		Note: "lab ci trigger" differs from "lab ci create" which is a different API
-	`),
+		Note: "lab ci trigger" differs from "lab ci create" which is a different API`),
 	Example: heredoc.Doc(`
 		lab ci trigger feature_branch
 		lab ci trigger -p engineering/integration_tests master
-		lab ci trigger -p engineering/integration_tests -v foo=bar master
-	`),
+		lab ci trigger -p engineering/integration_tests -v foo=bar master`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		pid, branch, err := getCIRunOptions(cmd, args)

cmd/ci_status.go

@@ -22,8 +22,8 @@ var ciStatusCmd = &cobra.Command{
 	Short:   "Textual representation of a CI pipeline",
 	Example: heredoc.Doc(`
 		lab ci status
-		lab ci status --wait
-	`),
+		lab ci status upstream 608 --merge-request
+		lab ci status 600 --wait`),
 	RunE:             nil,
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {

cmd/ci_trace.go

@@ -32,13 +32,11 @@ var ciTraceCmd = &cobra.Command{
 		The branch name, when using with the --merge-request option, can be the
 		merge request number, which matches the branch name internally.	The "job"
 		portion is the given job name, which may contain whitespace characters
-		and which, for this specific case, must be quoted.
-	`),
+		and which, for this specific case, must be quoted.`),
 	Example: heredoc.Doc(`
 		lab ci trace upstream feature_branch
 		lab ci trace upstream 18 --merge-request
-		lab ci trace upstream 18:'my custom stage' --merge-request
-	`),
+		lab ci trace upstream 18:'my custom stage' --merge-request`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		var (

cmd/ci_view.go

@@ -42,8 +42,10 @@ var ciViewCmd = &cobra.Command{
 		'r', 'p' to run/retry/play a job
 		't' to toggle trace/logs (runs in background)
 		'T' to toggle trace/logs (suspending application)
-		'c' to cancel job
-	`),
+		'c' to cancel job`),
+	Example: heredoc.Doc(`
+		lab ci view
+		lab ci view upstream --merge-request`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		a := tview.NewApplication()

cmd/clone.go

@@ -18,13 +18,11 @@ var cloneCmd = &cobra.Command{
 	Short: "GitLab aware clone repo command",
 	Long: heredoc.Doc(`
 		Clone a repository, similarly to 'git clone', but aware of GitLab
-		specific settings.
-	`),
+		specific settings.`),
 	Example: heredoc.Doc(`
 		lab clone awesome-repo
-		lab clone company/awesome-repo
-		lab clone company/backend-team/awesome-repo
-	`),
+		lab clone company/awesome-repo --http
+		lab clone company/backend-team/awesome-repo`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		project, err := gitlab.FindProject(args[0])

cmd/completion.go

@@ -17,17 +17,15 @@ var completionCmd = &cobra.Command{
 		Generates shell autocompletion scripts for different implementations.
 
 		These scripts can be directly sourced, though using pre-generated
-		versions is recommended to avoid shell startup delay.
-	`),
+		versions is recommended to avoid shell startup delay.`),
 	Example: heredoc.Doc(`
 		bash       : source <(lab completion)
 		elvish     : eval(lab completion|slurp)
 		fish       : lab completion | source
 		oil        : source <(lab completion)
 		powershell : lab completion | Out-String | Invoke-Expression
-		xonsh      : exec($(lab completion))
-		zsh        : source <(lab completion)
-	`),
+		xonsh      : exec($(lab completion xonsh))
+		zsh        : source <(lab completion zsh)`),
 	ValidArgs: []string{"bash", "elvish", "fish", "oil", "powershell", "xonsh", "zsh"},
 	Run: func(cmd *cobra.Command, args []string) {
 		shell := ""

cmd/fork.go

@@ -30,13 +30,15 @@ var forkCmd = &cobra.Command{
 	Short: "Fork a remote repository on GitLab and add as remote",
 	Long: heredoc.Doc(`
 		Fork a remote repository on user's location of choice.
-		Both an already existent remote or a repository path can be specified.
-	`),
+		Both an already existent remote or a repository path can be specified.`),
 	Example: heredoc.Doc(`
 		lab fork origin
 		lab fork upstream --remote-name origin
-		lab fork origin --name new-awasome-project
-	`),
+		lab fork origin --name new-awesome-project
+		lab fork origin -g TheCoolestGroup -n InitialProject
+		lab fork origin -p 'the_dot_git_path'
+		lab fork origin -n 'new_fork' -r 'new_fork_remote'
+		lab fork origin -s`),
 	Args:             cobra.MaximumNArgs(1),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {

cmd/issue_browse.go

@@ -1,6 +1,7 @@
 package cmd
 
 import (
+	"github.com/MakeNowJust/heredoc/v2"
 	"strconv"
 
 	"github.com/rsteube/carapace"
@@ -10,9 +11,12 @@ import (
 )
 
 var issueBrowseCmd = &cobra.Command{
-	Use:              "browse [remote] <id>",
-	Aliases:          []string{"b"},
-	Short:            "View issue in a browser",
+	Use:     "browse [remote] <id>",
+	Aliases: []string{"b"},
+	Short:   "View issue in a browser",
+	Example: heredoc.Doc(`
+		lab issue browse
+		lab issue browse upstream 22`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		rn, num, err := parseArgsRemoteAndID(args)

cmd/issue_close.go

@@ -19,9 +19,8 @@ var issueCloseCmd = &cobra.Command{
 	PersistentPreRun: labPersistentPreRun,
 	Example: heredoc.Doc(`
 		lab issue close 1234
-		lab issue close --duplicate 123 1234
-		lab issue close --duplicate other-project#123 1234
-	`),
+		lab issue close origin --duplicate 123 1234
+		lab issue close --duplicate other-project#123 1234`),
 	Run: func(cmd *cobra.Command, args []string) {
 		rn, id, err := parseArgsRemoteAndID(args)
 		if err != nil {

cmd/issue_create.go

@@ -19,10 +19,17 @@ import (
 )
 
 var issueCreateCmd = &cobra.Command{
-	Use:              "create [remote]",
-	Aliases:          []string{"new"},
-	Short:            "Open an issue on GitLab",
-	Args:             cobra.MaximumNArgs(1),
+	Use:     "create [remote]",
+	Aliases: []string{"new"},
+	Short:   "Open an issue on GitLab",
+	Args:    cobra.MaximumNArgs(1),
+	Example: heredoc.Doc(`
+		lab issue create
+		lab issue create origin -a johndoe -a janedoe
+		lab issue create origin -l bug
+		lab issue create upstream -m "new issue related to the --help arg"
+		lab issue create upstream --milestone "July"
+		lab issue create upstream --template "API-BUG"`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		msgs, err := cmd.Flags().GetStringArray("message")

cmd/issue_edit.go

@@ -22,12 +22,14 @@ var issueEditCmd = &cobra.Command{
 	Aliases: []string{"update"},
 	Short:   "Edit or update an issue",
 	Example: heredoc.Doc(`
-		lab issue edit <id>
-		lab issue edit <id> -m "new title"
-		lab issue edit <id> -m "new title" -m "new desc"
-		lab issue edit <id> -l new_label --unlabel old_label
-		lab issue edit <id>:<comment_id>
-	`),
+		lab issue edit 14
+		lab issue edit 14:2065489
+		lab issue edit 14 -a johndoe --unassign jackdoe
+		lab issue edit 14 -m "new title"
+		lab issue edit 14 -m "new title" -m "new desc"
+		lab issue edit 14 -l new_label --unlabel old_label
+		lab issue edit --milestone "NewYear"
+		lab issue edit --force-linebreak`),
 	Args:             cobra.MinimumNArgs(1),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {

cmd/issue_list.go

@@ -36,8 +36,17 @@ var issueListCmd = &cobra.Command{
 	Example: heredoc.Doc(`
 		lab issue list
 		lab issue list "search terms"
-		lab issue list remote "search terms"
-	`),
+		lab issue list origin "search terms"
+		lab issue list origin --all
+		lab issue list origin --assignee johndoe
+		lab issue list upstream --author janedoe
+		lab issue list upstream -x "An Issue with Abc"
+		lab issue list upstream -l "new_bug"
+		lab issue list upstream --milestone "week 22"
+		lab issue list remote -n "10"
+		lab issue list remote --order "created_at"
+		lab issue list remote --sort "asc"
+		lab issue list remote --state "closed"`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		issues, err := issueList(args)

cmd/issue_note.go

@@ -1,16 +1,22 @@
 package cmd
 
 import (
+	"github.com/MakeNowJust/heredoc/v2"
 	"github.com/rsteube/carapace"
 	"github.com/spf13/cobra"
 	"github.com/zaquestion/lab/internal/action"
 )
 
 var issueNoteCmd = &cobra.Command{
-	Use:              "note [remote] <id>[:<comment_id>]",
-	Aliases:          []string{"comment", "reply"},
-	Short:            "Add a note or comment to an issue on GitLab",
-	Args:             cobra.MinimumNArgs(1),
+	Use:     "note [remote] <id>[:<comment_id>]",
+	Aliases: []string{"comment", "reply"},
+	Short:   "Add a note or comment to an issue on GitLab",
+	Args:    cobra.MinimumNArgs(1),
+	Example: heredoc.Doc(`
+		lab issue note 1
+		lab issue note 2 -F test_file --force-linebreak
+		lab issue note origin 2 -m "a message" -m "another one"
+		lab issue note upstream 1:613278106 --quote`),
 	PersistentPreRun: labPersistentPreRun,
 	Run:              noteRunFn,
 }
@@ -19,8 +25,9 @@ func init() {
 	issueNoteCmd.Flags().StringArrayP("message", "m", []string{}, "use the given <msg>; multiple -m are concatenated as separate paragraphs")
 	issueNoteCmd.Flags().StringP("file", "F", "", "use the given file as the message")
 	issueNoteCmd.Flags().Bool("force-linebreak", false, "append 2 spaces to the end of each line to force markdown linebreaks")
-	issueNoteCmd.Flags().Bool("quote", false, "quote note in reply (used with --reply only)")
+	issueNoteCmd.Flags().Bool("quote", false, "quote note in reply")
 	issueNoteCmd.Flags().Bool("resolve", false, "[unused in issue note command]")
+	issueNoteCmd.Flags().MarkHidden("resolve")
 
 	issueCmd.AddCommand(issueNoteCmd)
 	carapace.Gen(issueNoteCmd).PositionalCompletion(

cmd/issue_reopen.go

@@ -2,6 +2,7 @@ package cmd
 
 import (
 	"fmt"
+	"github.com/MakeNowJust/heredoc/v2"
 
 	"github.com/rsteube/carapace"
 	"github.com/spf13/cobra"
@@ -10,8 +11,11 @@ import (
 )
 
 var issueReopenCmd = &cobra.Command{
-	Use:              "reopen [remote] <id>",
-	Short:            "Reopen a closed issue",
+	Use:   "reopen [remote] <id>",
+	Short: "Reopen a closed issue",
+	Example: heredoc.Doc(`
+		lab issue reopen 1
+		lab issue reopen upstream 2`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		rn, id, err := parseArgsRemoteAndID(args)

cmd/issue_show.go

@@ -15,17 +15,25 @@ import (
 )
 
 var issueShowCmd = &cobra.Command{
-	Use:              "show [remote] <id>",
-	Aliases:          []string{"get"},
-	ArgAliases:       []string{"s"},
-	Short:            "Describe an issue",
+	Use:        "show [remote] <id>",
+	Aliases:    []string{"get"},
+	ArgAliases: []string{"s"},
+	Short:      "Describe an issue",
+	Example: heredoc.Doc(`
+		lab issue show 1
+		lab issue show origin 1 -c
+		lab issue show upstream 1 -M
+		lab issue show upstream 1 --since "1970-01-01 00:00:00.000 +0000 UTC"`),
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 
 		rn, issueNum, err := parseArgsRemoteAndID(args)
 		if err != nil {
 			log.Fatal(err)
 		}
+		if issueNum == 0 {
+			log.Fatalf("Specify <id> of issue to be show")
+		}
 
 		issue, err := lab.IssueGet(rn, int(issueNum))
 		if err != nil {

cmd/issue_subscribe.go

@@ -13,6 +13,7 @@ var issueSubscribeCmd = &cobra.Command{
 	Use:              "subscribe [remote] <id>",
 	Aliases:          []string{},
 	Short:            "Subscribe to an issue",
+	Example:          "lab issue subscribe origin 10",
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		rn, id, err := parseArgsRemoteAndID(args)

cmd/issue_unsubscribe.go

@@ -14,6 +14,7 @@ var issueUnsubscribeCmd = &cobra.Command{
 	Aliases:          []string{},
 	Short:            "Unubscribe from an issue",
 	Long:             ``,
+	Example:          "lab issue unsubscribe origin 10",
 	PersistentPreRun: labPersistentPreRun,
 	Run: func(cmd *cobra.Command, args []string) {
 		rn, id, err := parseArgsRemoteAndID(args)

cmd/label_create.go

@@ -16,8 +16,7 @@ var labelCreateCmd = &cobra.Command{
 	Example: heredoc.Doc(`
 		lab label create my-label
 		lab label create --color cornflowerblue --description "Blue as a cornflower" blue
-		lab label create --color #6495ed --description "Also blue as a cornflower" blue2
-	`),
+		lab label create --color #6495ed --description "Also blue as a cornflower" blue2`),
 	PersistentPreRun: labPersistentPreRun,
 	Args:             cobra.MinimumNArgs(1),
 	Run: func(cmd *cobra.Command, args []string) {