Proper help text & new README structure (#311)

add cli.AppHelpTemplate for customization

customize tea help view

tea --version : improve parseability

Rework README to include tea help output

It's an antipattern to have different help texts aimed at the same
users. So now that we have a good cli help text, lets use it here.
This eases maintenance, and at the same time gives an honest impression
on what we have to offer, while also encouraging to improve the internal
help text in the future.

I feel a bit sad for the GIF, but it was becoming outdated anyway..

group commands by category

add new demo gif

shows the (probably) most useful workflow

readme improvement

Merge branch 'master' into improve-app-help

code review

Merge branch 'master' into improve-app-help

restructure installation section

Co-authored-by: Norwin Roosen <git@nroo.de>
Reviewed-on: https://gitea.com/gitea/tea/pulls/311
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-by: khmarbaise <khmarbaise@noreply.gitea.io>
Co-Authored-By: Norwin <noerw@noreply.gitea.io>
Co-Committed-By: Norwin <noerw@noreply.gitea.io>

README.md

@@ -2,67 +2,95 @@
 
 [![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT) [![Release](https://raster.shields.io/badge/dynamic/json.svg?label=release&url=https://gitea.com/api/v1/repos/gitea/tea/releases&query=$[0].tag_name)](https://gitea.com/gitea/tea/releases) [![Build Status](https://drone.gitea.com/api/badges/gitea/tea/status.svg)](https://drone.gitea.com/gitea/tea) [![Join the chat at https://img.shields.io/discord/322538954119184384.svg](https://img.shields.io/discord/322538954119184384.svg)](https://discord.gg/Gitea) [![Go Report Card](https://goreportcard.com/badge/code.gitea.io/tea)](https://goreportcard.com/report/code.gitea.io/tea) [![GoDoc](https://godoc.org/code.gitea.io/tea?status.svg)](https://godoc.org/code.gitea.io/tea)
 
-## The official CLI interface for gitea
+### The official CLI for Gitea
 
-Tea is a command line tool for interacting on one or more Gitea instances.
+![demo gif](./demo.gif)
-It uses [code.gitea.io/sdk](https://code.gitea.io/sdk) and interacts with the Gitea API
 
-![demo gif](https://dl.gitea.io/screenshots/tea_demo.gif)
+```
+   tea - command line tool to interact with Gitea
+   version 0.7.0-preview
 
-For a feature comparison with other git forge CLIs see [here](./FEATURE-COMPARISON.md).
+ USAGE
+   tea command [subcommand] [command options] [arguments...]
+
+ DESCRIPTION
+   tea is a productivity helper for Gitea.  It can be used to manage most entities on one
+   or multiple Gitea instances and provides local helpers like 'tea pull checkout'.
+   tea makes use of context provided by the repository in $PWD if available, but is still
+   usable independently of $PWD. Configuration is persisted in $XDG_CONFIG_HOME/tea.
+
+ COMMANDS
+   help, h  Shows a list of commands or help for one command
+   ENTITIES:
+     issues, issue, i                  List, create and update issues
+     pulls, pull, pr                   Manage and checkout pull requests
+     labels, label                     Manage issue labels
+     milestones, milestone, ms         List and create milestones
+     releases, release, r              Manage releases
+     times, time, t                    Operate on tracked times of a repository's issues & pulls
+     organizations, organization, org  List, create, delete organizations
+     repos, repo                       Show repository details
+   HELPERS:
+     open, o                         Open something of the repository in web browser
+     notifications, notification, n  Show notifications
+   SETUP:
+     logins, login                  Log in to a Gitea server
+     logout                         Log out from a Gitea server
+     shellcompletion, autocomplete  Install shell completion for tea
+
+ OPTIONS
+   --help, -h     show help (default: false)
+   --version, -v  print the version (default: false)
+
+ EXAMPLES
+   tea login add                       # add a login once to get started
+
+   tea pulls                           # list open pulls for the repo in $PWD
+   tea pulls --repo $HOME/foo          # list open pulls for the repo in $HOME/foo
+   tea pulls --remote upstream         # list open pulls for the repo pointed at by
+                                       # your local "upstream" git remote
+   # list open pulls for any gitea repo at the given login instance
+   tea pulls --repo gitea/tea --login gitea.com
+
+   tea milestone issues 0.7.0          # view open issues for milestone '0.7.0'
+   tea issue 189                       # view contents of issue 189
+   tea open 189                        # open web ui for issue 189
+   tea open milestones                 # open web ui for milestones
+
+   # send gitea desktop notifications every 5 minutes (bash + libnotify)
+   while :; do tea notifications --all -o simple | xargs -i notify-send {}; sleep 300; done
+
+ ABOUT
+   Written & maintained by The Gitea Authors.
+   If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
+   More info about Gitea itself on https://gitea.io.
+```
+
+- [Compare features with other git forge CLIs](./FEATURE-COMPARISON.md)
+- tea uses [code.gitea.io/sdk](https://code.gitea.io/sdk) and interacts with the Gitea API.
 
 ## Installation
 
-You can use the prebuilt binaries from [dl.gitea.io](https://dl.gitea.io/tea/)
+There are different ways to get `tea`:
 
-To install from source, go 1.13 or newer is required:
+1. Install via your system package manager:
+    - macOS via `brew` (gitea-maintained):
+      ```sh
+      brew tap gitea/tap https://gitea.com/gitea/homebrew-gitea
+      brew install tea
+      ```
+    - arch linux ([gitea-tea](https://aur.archlinux.org/packages/gitea-tea), thirdparty)
+    - alpine linux ([tea](https://pkgs.alpinelinux.org/packages?name=tea&branch=edge), thirdparty)
 
-```sh
+2. Use the prebuilt binaries from [dl.gitea.io](https://dl.gitea.io/tea/)
-go get code.gitea.io/tea
-go install code.gitea.io/tea
-```
 
-If you have `brew` installed, you can install `tea` via:
+3. Install from source (go 1.13 or newer is required):
+    ```sh
+    go get code.gitea.io/tea
+    go install code.gitea.io/tea
+    ```
 
-```sh
+4. Docker (thirdparty): [tgerczei/tea](https://hub.docker.com/r/tgerczei/tea)
-brew tap gitea/tap https://gitea.com/gitea/homebrew-gitea
-brew install tea
-```
-
-Distribution packages exist for: **alpinelinux ([tea](https://pkgs.alpinelinux.org/packages?name=tea&branch=edge))** and **archlinux ([gitea-tea](https://aur.archlinux.org/packages/gitea-tea))**
-
-
-Shell completion can be added via `tea autocomplete --install`.
-
-## Usage
-
-First of all, you have to create a token on your `personal settings -> application` page of your gitea instance.
-Use this token to login with `tea`:
-
-```sh
-tea login add --name=try --url=https://try.gitea.io --token=xxxxxx
-```
-
-Now you can use the following `tea` subcommands.
-Detailed usage information is available via `tea <command> --help`.
-
-```none
-login            Log in to a Gitea server
-logout           Log out from a Gitea server
-issues           List, create and update issues
-pulls            List, create, checkout and clean pull requests
-releases         List, create, update and delete releases
-repos            Operate with repositories
-labels           Manage issue labels
-times            Operate on tracked times of a repositorys issues and pulls
-open             Open something of the repository on web browser
-notifications    Show notifications
-milestones       List and create milestones
-organizations    List, create, delete organizations
-help, h          Shows a list of commands or help for one command
-```
-
-To fetch issues from different repos, use the `--remote` flag (when inside a gitea repository directory) or `--login` & `--repo` flags.
 
 ## Compilation
 

cmd/autocomplete.go

@@ -19,6 +19,7 @@ import (
 var CmdAutocomplete = cli.Command{
 	Name:        "shellcompletion",
 	Aliases:     []string{"autocomplete"},
+	Category:    catSetup,
 	Usage:       "Install shell completion for tea",
 	Description: "Install shell completion for tea",
 	ArgsUsage:   "<shell type> (bash, zsh, powershell)",

cmd/categories.go

@@ -0,0 +1,11 @@
+// Copyright 2020 The Gitea Authors. All rights reserved.
+// Use of this source code is governed by a MIT-style
+// license that can be found in the LICENSE file.
+
+package cmd
+
+var (
+	catSetup    = "SETUP"
+	catEntities = "ENTITIES"
+	catHelpers  = "HELPERS"
+)

cmd/issues.go

@@ -18,6 +18,7 @@ import (
 var CmdIssues = cli.Command{
 	Name:        "issues",
 	Aliases:     []string{"issue", "i"},
+	Category:    catEntities,
 	Usage:       "List, create and update issues",
 	Description: "List, create and update issues",
 	ArgsUsage:   "[<issue index>]",

cmd/labels.go

@@ -15,6 +15,7 @@ import (
 var CmdLabels = cli.Command{
 	Name:        "labels",
 	Aliases:     []string{"label"},
+	Category:    catEntities,
 	Usage:       "Manage issue labels",
 	Description: `Manage issue labels`,
 	Action:      runLabels,

cmd/login.go

@@ -18,6 +18,7 @@ import (
 var CmdLogin = cli.Command{
 	Name:        "logins",
 	Aliases:     []string{"login"},
+	Category:    catSetup,
 	Usage:       "Log in to a Gitea server",
 	Description: `Log in to a Gitea server`,
 	ArgsUsage:   "[<login name>]",

cmd/logout.go

@@ -13,6 +13,7 @@ import (
 // CmdLogout represents to logout a gitea server.
 var CmdLogout = cli.Command{
 	Name:        "logout",
+	Category:    catSetup,
 	Usage:       "Log out from a Gitea server",
 	Description: `Log out from a Gitea server`,
 	ArgsUsage:   "<login name>",

cmd/milestones.go

@@ -17,6 +17,7 @@ import (
 var CmdMilestones = cli.Command{
 	Name:        "milestones",
 	Aliases:     []string{"milestone", "ms"},
+	Category:    catEntities,
 	Usage:       "List and create milestones",
 	Description: `List and create milestones`,
 	ArgsUsage:   "[<milestone name>]",

cmd/notifications.go

@@ -17,6 +17,7 @@ import (
 var CmdNotifications = cli.Command{
 	Name:        "notifications",
 	Aliases:     []string{"notification", "n"},
+	Category:    catHelpers,
 	Usage:       "Show notifications",
 	Description: "Show notifications, by default based of the current repo and unread one",
 	Action:      runNotifications,

cmd/open.go

@@ -20,6 +20,7 @@ import (
 var CmdOpen = cli.Command{
 	Name:        "open",
 	Aliases:     []string{"o"},
+	Category:    catHelpers,
 	Usage:       "Open something of the repository in web browser",
 	Description: `Open something of the repository in web browser`,
 	Action:      runOpen,

cmd/organizations.go

@@ -16,6 +16,7 @@ import (
 var CmdOrgs = cli.Command{
 	Name:        "organizations",
 	Aliases:     []string{"organization", "org"},
+	Category:    catEntities,
 	Usage:       "List, create, delete organizations",
 	Description: "Show organization details",
 	ArgsUsage:   "[<organization>]",

cmd/pulls.go

@@ -21,6 +21,7 @@ import (
 var CmdPulls = cli.Command{
 	Name:        "pulls",
 	Aliases:     []string{"pull", "pr"},
+	Category:    catEntities,
 	Usage:       "Manage and checkout pull requests",
 	Description: `Manage and checkout pull requests`,
 	ArgsUsage:   "[<pull index>]",

cmd/releases.go

@@ -16,6 +16,7 @@ import (
 var CmdReleases = cli.Command{
 	Name:        "releases",
 	Aliases:     []string{"release", "r"},
+	Category:    catEntities,
 	Usage:       "Manage releases",
 	Description: "Manage releases",
 	Action:      releases.RunReleasesList,

cmd/repos.go

@@ -18,6 +18,7 @@ import (
 var CmdRepos = cli.Command{
 	Name:        "repos",
 	Aliases:     []string{"repo"},
+	Category:    catEntities,
 	Usage:       "Show repository details",
 	Description: "Show repository details",
 	ArgsUsage:   "[<repo owner>/<repo name>]",

cmd/times.go

@@ -11,9 +11,10 @@ import (
 
 // CmdTrackedTimes represents the command to operate repositories' times.
 var CmdTrackedTimes = cli.Command{
-	Name:    "times",
+	Name:     "times",
-	Aliases: []string{"time", "t"},
+	Aliases:  []string{"time", "t"},
-	Usage:   "Operate on tracked times of a repository's issues & pulls",
+	Category: catEntities,
+	Usage:    "Operate on tracked times of a repository's issues & pulls",
 	Description: `Operate on tracked times of a repository's issues & pulls.
 		 Depending on your permissions on the repository, only your own tracked
 		 times might be listed.`,

main.go

@@ -22,24 +22,31 @@ var Version = "development"
 var Tags = ""
 
 func main() {
+	// make parsing tea --version easier, by printing /just/ the version string
+	cli.VersionPrinter = func(c *cli.Context) { fmt.Fprintln(c.App.Writer, c.App.Version) }
+
 	app := cli.NewApp()
 	app.Name = "tea"
-	app.Usage = "Command line tool to interact with Gitea"
+	app.Usage = "command line tool to interact with Gitea"
+	app.Description = appDescription
+	app.CustomAppHelpTemplate = helpTemplate
 	app.Version = Version + formatBuiltWith(Tags)
 	app.Commands = []*cli.Command{
 		&cmd.CmdLogin,
 		&cmd.CmdLogout,
+		&cmd.CmdAutocomplete,
+
 		&cmd.CmdIssues,
 		&cmd.CmdPulls,
-		&cmd.CmdReleases,
-		&cmd.CmdRepos,
 		&cmd.CmdLabels,
+		&cmd.CmdMilestones,
+		&cmd.CmdReleases,
 		&cmd.CmdTrackedTimes,
+		&cmd.CmdOrgs,
+		&cmd.CmdRepos,
+
 		&cmd.CmdOpen,
 		&cmd.CmdNotifications,
-		&cmd.CmdMilestones,
-		&cmd.CmdOrgs,
-		&cmd.CmdAutocomplete,
 	}
 	app.EnableBashCompletion = true
 	err := app.Run(os.Args)
@@ -58,3 +65,56 @@ func formatBuiltWith(Tags string) string {
 
 	return " built with: " + strings.Replace(Tags, " ", ", ", -1)
 }
+
+var appDescription = `tea is a productivity helper for Gitea.  It can be used to manage most entities on one
+or multiple Gitea instances and provides local helpers like 'tea pull checkout'.
+tea makes use of context provided by the repository in $PWD if available, but is still
+usable independently of $PWD. Configuration is persisted in $XDG_CONFIG_HOME/tea.
+`
+
+var helpTemplate = bold(`
+   {{.Name}}{{if .Usage}} - {{.Usage}}{{end}}`) + `
+   {{if .Version}}{{if not .HideVersion}}version {{.Version}}{{end}}{{end}}
+
+ USAGE
+   {{if .UsageText}}{{.UsageText}}{{else}}{{.HelpName}}{{if .Commands}} command [subcommand] [command options]{{end}} {{if .ArgsUsage}}{{.ArgsUsage}}{{else}}[arguments...]{{end}}{{end}}{{if .Description}}
+
+ DESCRIPTION
+   {{.Description | nindent 3 | trim}}{{end}}{{if .VisibleCommands}}
+
+ COMMANDS{{range .VisibleCategories}}{{if .Name}}
+   {{.Name}}:{{range .VisibleCommands}}
+     {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{else}}{{range .VisibleCommands}}
+   {{join .Names ", "}}{{"\t"}}{{.Usage}}{{end}}{{end}}{{end}}{{end}}{{if .VisibleFlags}}
+
+ OPTIONS
+   {{range $index, $option := .VisibleFlags}}{{if $index}}
+   {{end}}{{$option}}{{end}}{{end}}
+
+ EXAMPLES
+   tea login add                       # add a login once to get started
+
+   tea pulls                           # list open pulls for the repo in $PWD
+   tea pulls --repo $HOME/foo          # list open pulls for the repo in $HOME/foo
+   tea pulls --remote upstream         # list open pulls for the repo pointed at by
+                                       # your local "upstream" git remote
+   # list open pulls for any gitea repo at the given login instance
+   tea pulls --repo gitea/tea --login gitea.com
+
+   tea milestone issues 0.7.0          # view open issues for milestone '0.7.0'
+   tea issue 189                       # view contents of issue 189
+   tea open 189                        # open web ui for issue 189
+   tea open milestones                 # open web ui for milestones
+
+   # send gitea desktop notifications every 5 minutes (bash + libnotify)
+   while :; do tea notifications --all -o simple | xargs -i notify-send {}; sleep 300; done
+
+ ABOUT
+   Written & maintained by The Gitea Authors.
+   If you find a bug or want to contribute, we'll welcome you at https://gitea.com/gitea/tea.
+   More info about Gitea itself on https://gitea.io.
+`
+
+func bold(t string) string {
+	return fmt.Sprintf("\033[1m%s\033[0m", t)
+}