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>

README.md

@@ -144,6 +144,21 @@ tea completion fish > ~/.config/fish/completions/tea.fish
 Output the script to path/to/autocomplete/tea.ps1 an run it.
 ```
 
+### Man Page
+
+The hidden command `tea man` can be used to generate the `tea` man page.
+
+```shell
+# for bash or zsh
+man <(tea man)
+
+# for fish
+man (tea man | psub)
+
+# write man page to a file
+tea man --out ./tea.man
+```
+
 ## Compilation
 
 Make sure you have a current go version installed (1.13 or newer).

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
+}

docs/docs.go

@@ -6,9 +6,7 @@ package main
 
 import (
 	"context"
-	"fmt"
 	"os"
-	"path/filepath"
 
 	"code.gitea.io/tea/cmd"
 	docs "github.com/urfave/cli-docs/v3"
@@ -21,40 +19,9 @@ func main() {
 		Name:        "docs",
 		Hidden:      true,
 		Description: "Generate CLI docs",
-		Action: func(ctx context.Context, c *cli.Command) error {
-
-			md, err := docs.ToMarkdown(cmd.App())
-			if err != nil {
-				return err
-			}
-			outPath := c.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
-
-		},
-		Flags: []cli.Flag{
-			&cli.StringFlag{
-				Name:    "out",
-				Usage:   "Path to output docs to, otherwise prints to stdout",
-				Aliases: []string{"o"},
-			},
+		Flags:       cmd.DocRenderFlags,
+		Action: func(ctx context.Context, params *cli.Command) error {
+			return cmd.RenderDocs(params, cmd.App(), docs.ToMarkdown)
 		},
 	}
 	cli.Run(context.Background(), os.Args)