feat: add generate-docs command with markdown and man page support

.goreleaser.yaml

@@ -9,6 +9,7 @@ before:
         - sh -c "mkdir -p completions && go run ./cmd/pinner completion bash > completions/pinner.bash"
         - sh -c "go run ./cmd/pinner completion zsh > completions/pinner.zsh"
         - sh -c "go run ./cmd/pinner completion fish > completions/pinner.fish"
+        - sh -c "mkdir -p manpages && go run ./cmd/pinner generate-docs man -o manpages/pinner.1"
 
 builds:
     - id: pinner-cli
@@ -46,6 +47,7 @@ archives:
           - LICENSE
           - README.md
           - completions/*
+          - manpages/*
 
 checksum:
     name_template: checksums.txt
@@ -79,6 +81,8 @@ nfpms:
             dst: /usr/share/zsh/site-functions/_pinner
           - src: ./completions/pinner.fish
             dst: /usr/share/fish/vendor_completions.d/pinner.fish
+          - src: ./manpages/pinner.1
+            dst: /usr/share/man/man1/pinner.1
 
 homebrew_casks:
     - name: pinner

go.mod

@@ -49,6 +49,7 @@ require (
 	github.com/containerd/console v1.0.5 // indirect
 	github.com/coreos/go-semver v0.3.1 // indirect
 	github.com/coreos/go-systemd/v22 v22.6.0 // indirect
+	github.com/cpuguy83/go-md2man/v2 v2.0.2 // indirect
 	github.com/crackcomm/go-gitignore v0.0.0-20241020182519-7843d2ba8fdf // indirect
 	github.com/davecgh/go-spew v1.1.2-0.20180830191138-d8f796af33cc // indirect
 	github.com/decred/dcrd/dcrec/secp256k1/v4 v4.4.0 // indirect
@@ -142,10 +143,12 @@ require (
 	github.com/prometheus/common v0.66.1 // indirect
 	github.com/prometheus/procfs v0.17.0 // indirect
 	github.com/rs/cors v1.11.1 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spaolacci/murmur3 v1.1.0 // indirect
 	github.com/spf13/cast v1.10.0 // indirect
 	github.com/stretchr/objx v0.5.2 // indirect
 	github.com/ucarion/urlpath v0.0.0-20200424170820-7ccc79b76bbb // indirect
+	github.com/urfave/cli-docs/v3 v3.1.1-0.20251022123016-72b87d11c482 // indirect
 	github.com/valyala/bytebufferpool v1.0.0 // indirect
 	github.com/valyala/fasttemplate v1.2.2 // indirect
 	github.com/whyrusleeping/base32 v0.0.0-20170828182744-c30ac30633cc // indirect

go.sum

@@ -119,6 +119,8 @@ github.com/coreos/go-systemd/v22 v22.6.0 h1:aGVa/v8B7hpb0TKl0MWoAavPDmHvobFe5R5z
 github.com/coreos/go-systemd/v22 v22.6.0/go.mod h1:iG+pp635Fo7ZmV/j14KUcmEyWF+0X7Lua8rrTWzYgWU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0-20190314233015-f79a8a8ca69d/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
 github.com/cpuguy83/go-md2man/v2 v2.0.0/go.mod h1:maD7wRr/U5Z6m/iR4s+kqSMx2CaBsrgA7czyZG/E6dU=
+github.com/cpuguy83/go-md2man/v2 v2.0.2 h1:p1EgwI/C7NhT0JmVkwCD2ZBK8j4aeHQX2pMHHBfMQ6w=
+github.com/cpuguy83/go-md2man/v2 v2.0.2/go.mod h1:tgQtvFlXSQOSOSIRvRPT7W67SCa46tRHOmNcaadrF8o=
 github.com/crackcomm/go-gitignore v0.0.0-20241020182519-7843d2ba8fdf h1:dwGgBWn84wUS1pVikGiruW+x5XM4amhjaZO20vCjay4=
 github.com/crackcomm/go-gitignore v0.0.0-20241020182519-7843d2ba8fdf/go.mod h1:p1d6YEZWvFzEh4KLyvBcVSnrfNDDvK2zfK/4x2v/4pE=
 github.com/cskr/pubsub v1.0.2 h1:vlOzMhl6PFn60gRlTQQsIfVwaPB/B/8MziK8FhEPt/0=
@@ -638,6 +640,8 @@ github.com/rogpeppe/go-internal v1.14.1/go.mod h1:MaRKkUm5W0goXpeCfT7UZI6fk/L7L7
 github.com/rs/cors v1.11.1 h1:eU3gRzXLRK57F5rKMGMZURNdIG4EoAmX8k94r9wXWHA=
 github.com/rs/cors v1.11.1/go.mod h1:XyqrcTp5zjWr1wsJ8PIRZssZ8b/WMcMf71DJnit4EMU=
 github.com/russross/blackfriday/v2 v2.0.1/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
+github.com/russross/blackfriday/v2 v2.1.0 h1:JIOH55/0cWyOuilr9/qlrm0BSXldqnqwMsf35Ld67mk=
+github.com/russross/blackfriday/v2 v2.1.0/go.mod h1:+Rmxgy9KzJVeS9/2gXHxylqXiyQDYRxCVz55jmeOWTM=
 github.com/ryanuber/columnize v0.0.0-20160712163229-9b3edd62028f/go.mod h1:sm1tb6uqfes/u+d4ooFouqFdy9/2g9QGwK3SQygK0Ts=
 github.com/samber/lo v1.53.0 h1:t975lj2py4kJPQ6haz1QMgtId2gtmfktACxIXArw3HM=
 github.com/samber/lo v1.53.0/go.mod h1:4+MXEGsJzbKGaUEQFKBq2xtfuznW9oz/WrgyzMzRoM0=
@@ -695,6 +699,10 @@ github.com/ucarion/urlpath v0.0.0-20200424170820-7ccc79b76bbb/go.mod h1:ikPs9bRW
 github.com/ugorji/go/codec v1.2.12 h1:9LC83zGrHhuUA9l16C9AHXAqEV/2wBQ4nkvumAE65EE=
 github.com/ugorji/go/codec v1.2.12/go.mod h1:UNopzCgEMSXjBc6AOMqYvWC1ktqTAfzJZUZgYf6w6lg=
 github.com/urfave/cli v1.22.10/go.mod h1:Gos4lmkARVdJ6EkW0WaNv/tZAAMe9V7XWyB60NtXRu0=
+github.com/urfave/cli-docs/v3 v3.1.0 h1:Sa5xm19IpE5gpm6tZzXdfjdFxn67PnEsE4dpXF7vsKw=
+github.com/urfave/cli-docs/v3 v3.1.0/go.mod h1:59d+5Hz1h6GSGJ10cvcEkbIe3j233t4XDqI72UIx7to=
+github.com/urfave/cli-docs/v3 v3.1.1-0.20251022123016-72b87d11c482 h1:xlSy8R55vuHbUM1c2mwfQ5MFeVTnm59BwQeWibPUD5A=
+github.com/urfave/cli-docs/v3 v3.1.1-0.20251022123016-72b87d11c482/go.mod h1:cjSVza4yCaqQet06zO6QhYqXQYjGRqbUj8zok6mHDRU=
 github.com/urfave/cli/v3 v3.6.1 h1:j8Qq8NyUawj/7rTYdBGrxcH7A/j7/G8Q5LhWEW4G3Mo=
 github.com/urfave/cli/v3 v3.6.1/go.mod h1:ysVLtOEmg2tOy6PknnYVhDoouyC/6N42TMeoMzskhso=
 github.com/valyala/bytebufferpool v1.0.0 h1:GqA5TC/0021Y/b9FG4Oi9Mr3q7XYx6KllzawFIhcdPw=

pkg/cli/command_registration_test.go

@@ -80,6 +80,7 @@ func TestCommandRegistration_RootSubcommands(t *testing.T) {
 		"ipns",
 		"websites",
 		"admin",
+		"generate-docs",
 	}
 
 	names := commandNames(root.Commands)

pkg/cli/docs.go

@@ -0,0 +1,68 @@
+package cli
+
+import (
+	"context"
+	"os"
+
+	docs "github.com/urfave/cli-docs/v3"
+	"github.com/urfave/cli/v3"
+)
+
+func newDocsCommand() *cli.Command {
+	return &cli.Command{
+		Name:     "generate-docs",
+		Usage:    "Generate CLI documentation in markdown or man format",
+		Category: "System",
+		Commands: []*cli.Command{
+			{
+				Name:  "markdown",
+				Usage: "Generate markdown documentation",
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:    "output",
+						Aliases: []string{"o"},
+						Usage:   "Output file (default: stdout)",
+					},
+				},
+				Action: func(ctx context.Context, cmd *cli.Command) error {
+					md, err := docs.ToMarkdown(NewRootCommand())
+					if err != nil {
+						return err
+					}
+					if out := cmd.String("output"); out != "" {
+						return os.WriteFile(out, []byte(md), 0o644)
+					}
+					_, err = cmd.Root().Writer.Write([]byte(md))
+					return err
+				},
+			},
+			{
+				Name:  "man",
+				Usage: "Generate man page documentation",
+				Flags: []cli.Flag{
+					&cli.StringFlag{
+						Name:    "output",
+						Aliases: []string{"o"},
+						Usage:   "Output file (default: stdout)",
+					},
+					&cli.IntFlag{
+						Name:  "section",
+						Usage: "Man section number",
+						Value: 1,
+					},
+				},
+				Action: func(ctx context.Context, cmd *cli.Command) error {
+					man, err := docs.ToManWithSection(NewRootCommand(), cmd.Int("section"))
+					if err != nil {
+						return err
+					}
+					if out := cmd.String("output"); out != "" {
+						return os.WriteFile(out, []byte(man), 0o644)
+					}
+					_, err = cmd.Root().Writer.Write([]byte(man))
+					return err
+				},
+			},
+		},
+	}
+}

pkg/cli/root.go

@@ -69,6 +69,7 @@ For more help on any command: pinner <command> --help`,
 			newIPNSCommand(),
 			newWebsitesCommand(),
 			newAdminCommand(),
+			newDocsCommand(),
 		},
 		Flags: GlobalFlags(),
 		Action: func(ctx context.Context, cmd *cli.Command) error {