generate man page (#811)

[CLI.md](src/branch/main/docs/CLI.md) already gets generated using `urfave/cli-docs`. `cli-docs` can also generate man pages.

This change extends the doc generator to also generate a man page for `tea`.

* Add a subcommand to the doc generator to print the generated man page to stdout

Closes #777.

Co-authored-by: Valentin Brandl <mail@vbrandl.net>
Reviewed-on: https://gitea.com/gitea/tea/pulls/811
Reviewed-by: Lunny Xiao <xiaolunwen@gmail.com>
Reviewed-by: TheFox0x7 <thefox0x7@noreply.gitea.com>
Co-authored-by: Valentin Brandl <vbrandl@noreply.gitea.com>
Co-committed-by: Valentin Brandl <vbrandl@noreply.gitea.com>

cmd/cmd.go

@@ -56,6 +56,8 @@ func App() *cli.Command {
 			&CmdRepoClone,
 
 			&CmdAdmin,
+
+			&CmdGenerateManPage,
 		},
 		EnableShellCompletion: true,
 	}

cmd/man.go

@@ -0,0 +1,62 @@
+// Copyright 2025 The Gitea Authors. All rights reserved.
+// SPDX-License-Identifier: MIT
+
+package cmd
+
+import (
+	"context"
+	"fmt"
+	"os"
+	"path/filepath"
+
+	docs "github.com/urfave/cli-docs/v3"
+	"github.com/urfave/cli/v3"
+)
+
+// DocRenderFlags are the flags for documentation generation, used by `./docs/docs.go` and the `generate-man-page` sub command
+var DocRenderFlags = []cli.Flag{
+	&cli.StringFlag{
+		Name:    "out",
+		Usage:   "Path to output docs to, otherwise prints to stdout",
+		Aliases: []string{"o"},
+	},
+}
+
+// CmdGenerateManPage is the sub command to generate the `tea` man page
+var CmdGenerateManPage = cli.Command{
+	Name:   "man",
+	Usage:  "Generate man page",
+	Hidden: true,
+	Flags:  DocRenderFlags,
+	Action: func(ctx context.Context, cmd *cli.Command) error {
+		return RenderDocs(cmd, cmd.Root(), docs.ToMan)
+	},
+}
+
+// RenderDocs renders the documentation for `target` using the supplied `render` function
+func RenderDocs(cmd, target *cli.Command, render func(*cli.Command) (string, error)) error {
+	out, err := render(target)
+	if err != nil {
+		return err
+	}
+	outPath := cmd.String("out")
+	if outPath == "" {
+		fmt.Print(out)
+		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(out); err != nil {
+		return err
+	}
+
+	return nil
+}