Initial CLI docs (#565)

As title, then we could potentially start ingesting these in the docs repo as they are expanded.

Reviewed-on: https://gitea.com/gitea/tea/pulls/565
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Co-authored-by: jolheiser <john.olheiser@gmail.com>
Co-committed-by: jolheiser <john.olheiser@gmail.com>

.gitea/workflows/test-pr.yml

@@ -20,6 +20,7 @@ jobs:
           make lint
           make fmt-check
           make misspell-check
+          make docs-check
           make build
         env:
           GOPROXY: https://goproxy.io,direct

Makefile

@@ -87,6 +87,19 @@ fmt-check:
 		exit 1; \
 	fi;
 
+.PHONY: docs
+docs:
+	$(GO) run . docs --out docs/CLI.md
+
+.PHONY: docs-check
+docs-check:
+	@DIFF=$$($(GO) run . docs | diff docs/CLI.md -); \
+	if [ -n "$$DIFF" ]; then \
+		echo "Please run 'make docs' and commit the result:"; \
+		echo "$$DIFF"; \
+		exit 1; \
+	fi;
+
 .PHONY: test
 test:
 	$(GO) test -tags='sqlite sqlite_unlock_notify' $(PACKAGES)

cmd/docs.go

@@ -0,0 +1,56 @@
+// Copyright 2023 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
+
+import (
+	"fmt"
+	"os"
+	"path/filepath"
+
+	"github.com/urfave/cli/v2"
+)
+
+// CmdDocs generates markdown for tea
+var CmdDocs = cli.Command{
+	Name:        "docs",
+	Hidden:      true,
+	Description: "Generate CLI docs",
+	Action:      runDocs,
+	Flags: []cli.Flag{
+		&cli.StringFlag{
+			Name:    "out",
+			Usage:   "Path to output docs to, otherwise prints to stdout",
+			Aliases: []string{"o"},
+		},
+	},
+}
+
+func runDocs(ctx *cli.Context) error {
+	md, err := ctx.App.ToMarkdown()
+	if err != nil {
+		return err
+	}
+
+	outPath := ctx.String("out")
+	if outPath == "" {
+		fmt.Print(md)
+		return nil
+	}
+
+	if err := os.MkdirAll(filepath.Dir(outPath), os.ModePerm); err != nil {
+		return err
+	}
+
+	fi, err := os.Create(outPath)
+	if err != nil {
+		return err
+	}
+	defer fi.Close()
+	if _, err := fi.WriteString(md); err != nil {
+		return err
+	}
+
+	return nil
+}

main.go

@@ -56,6 +56,7 @@ func main() {
 		&cmd.CmdRepoClone,
 
 		&cmd.CmdAdmin,
+		&cmd.CmdDocs,
 	}
 	app.EnableBashCompletion = true
 	err := app.Run(os.Args)