Makefile: add target to generate man pages (#5810)

Makefile

@@ -371,4 +371,20 @@ generate-docs: ## Generate docs (currently only for the cli)
 build-docs: generate-docs docs-dependencies ## Build the docs
 	(cd docs/; pnpm build)
 
+##@ Man Pages
+.PHONY: man-cli
+man-cli: ## Generate man pages for cli
+	mkdir -p dist/ && CGO_ENABLED=0 go run -tags man cmd/cli/man.go cmd/cli/app.go > dist/woodpecker-cli.man.1 && gzip -9 -f dist/woodpecker-cli.man.1
+
+.PHONY: man-agent
+man-agent: ## Generate man pages for agent
+	mkdir -p dist/ && CGO_ENABLED=0 go run -tags man cmd/agent/man.go > dist/woodpecker-agent.man.1 && gzip -9 -f dist/woodpecker-agent.man.1
+
+.PHONY: man-server
+man-server: ## Generate man pages for server
+	mkdir -p dist/ && CGO_ENABLED=0 go run -tags man go.woodpecker-ci.org/woodpecker/v3/cmd/server > dist/woodpecker-server.man.1 && gzip -9 -f dist/woodpecker-server.man.1
+
+.PHONY: man
+man: man-cli man-agent man-server ## Generate all man pages
+
 endif

cmd/agent/core/run.go

@@ -29,7 +29,7 @@ import (
 	"go.woodpecker-ci.org/woodpecker/v3/version"
 )
 
-func RunAgent(ctx context.Context, backends []backend.Backend) {
+func GenApp(backends []backend.Backend) *cli.Command {
 	app := &cli.Command{}
 	app.Name = "woodpecker-agent"
 	app.Version = version.String()
@@ -47,6 +47,11 @@ func RunAgent(ctx context.Context, backends []backend.Backend) {
 		agentFlags = utils.MergeSlices(agentFlags, b.Flags())
 	}
 	app.Flags = agentFlags
+	return app
+}
+
+func RunAgent(ctx context.Context, backends []backend.Backend) {
+	app := GenApp(backends)
 
 	if err := app.Run(ctx, os.Args); err != nil {
 		log.Fatal().Err(err).Msg("error running agent") //nolint:forbidigo

cmd/agent/man.go

@@ -0,0 +1,44 @@
+// Copyright 2025 Woodpecker Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build man
+
+package main
+
+import (
+	"fmt"
+
+	docs "github.com/urfave/cli-docs/v3"
+
+	"go.woodpecker-ci.org/woodpecker/v3/cmd/agent/core"
+	"go.woodpecker-ci.org/woodpecker/v3/pipeline/backend/docker"
+	"go.woodpecker-ci.org/woodpecker/v3/pipeline/backend/kubernetes"
+	"go.woodpecker-ci.org/woodpecker/v3/pipeline/backend/local"
+	backendTypes "go.woodpecker-ci.org/woodpecker/v3/pipeline/backend/types"
+)
+
+var backends = []backendTypes.Backend{
+	kubernetes.New(),
+	docker.New(),
+	local.New(),
+}
+
+func main() {
+	app := core.GenApp(backends)
+	md, err := docs.ToMan(app)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(md)
+}

cmd/cli/man.go

@@ -0,0 +1,32 @@
+// Copyright 2025 Woodpecker Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build man
+
+package main
+
+import (
+	"fmt"
+
+	docs "github.com/urfave/cli-docs/v3"
+)
+
+func main() {
+	app := newApp()
+	md, err := docs.ToMan(app)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(md)
+}

cmd/server/app.go

@@ -0,0 +1,39 @@
+// Copyright 2025 Woodpecker Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package main
+
+import (
+	"github.com/urfave/cli/v3"
+
+	"go.woodpecker-ci.org/woodpecker/v3/version"
+)
+
+func genApp() *cli.Command {
+	app := &cli.Command{}
+	app.Name = "woodpecker-server"
+	app.Version = version.String()
+	app.Usage = "woodpecker server"
+	app.Action = run
+	app.Commands = []*cli.Command{
+		{
+			Name:   "ping",
+			Usage:  "ping the server",
+			Action: pinger,
+		},
+	}
+	app.Flags = flags
+
+	return app
+}

cmd/server/main.go

@@ -12,7 +12,7 @@
 // See the License for the specific language governing permissions and
 // limitations under the License.
 
-//go:build !generate
+//go:build !generate && !man
 
 package main
 
@@ -22,11 +22,9 @@ import (
 
 	_ "github.com/joho/godotenv/autoload"
 	"github.com/rs/zerolog/log"
-	"github.com/urfave/cli/v3"
 
 	_ "go.woodpecker-ci.org/woodpecker/v3/cmd/server/openapi"
 	"go.woodpecker-ci.org/woodpecker/v3/shared/utils"
-	"go.woodpecker-ci.org/woodpecker/v3/version"
 )
 
 func main() {
@@ -34,19 +32,7 @@ func main() {
 		log.Info().Msg("termination signal is received, shutting down server")
 	})
 
-	app := cli.Command{}
-	app.Name = "woodpecker-server"
-	app.Version = version.String()
-	app.Usage = "woodpecker server"
-	app.Action = run
-	app.Commands = []*cli.Command{
-		{
-			Name:   "ping",
-			Usage:  "ping the server",
-			Action: pinger,
-		},
-	}
-	app.Flags = flags
+	app := genApp()
 
 	setupOpenAPIStaticConfig()
 

cmd/server/man.go

@@ -0,0 +1,35 @@
+// Copyright 2025 Woodpecker Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//      http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+//go:build man
+
+package main
+
+import (
+	"fmt"
+
+	_ "github.com/joho/godotenv/autoload"
+	docs "github.com/urfave/cli-docs/v3"
+
+	_ "go.woodpecker-ci.org/woodpecker/v3/cmd/server/openapi"
+)
+
+func main() {
+	app := genApp()
+	md, err := docs.ToMan(app)
+	if err != nil {
+		panic(err)
+	}
+	fmt.Print(md)
+}