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>

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",
-	Aliases: []string{"time", "t"},
-	Usage:   "Operate on tracked times of a repository's issues & pulls",
+	Name:     "times",
+	Aliases:  []string{"time", "t"},
+	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.`,