Merge pull request #1521 from afbjorklund/manpages

Include manpages for lima and limactl commands

Author: AkihiroSuda

Makefile

@@ -32,7 +32,7 @@ GO_BUILD := $(GO) build -ldflags="-s -w -X $(PACKAGE)/pkg/version.Version=$(VERS
 .NOTPARALLEL:
 
 .PHONY: all
-all: binaries
+all: binaries manpages
 
 exe: _output/bin/limactl$(exe)
 
@@ -113,6 +113,11 @@ _output/share/lima/lima-guestagent.Linux-riscv64:
 	GOOS=linux GOARCH=riscv64 CGO_ENABLED=0 $(GO_BUILD) -o $@ ./cmd/lima-guestagent
 	chmod 644 $@
 
+.PHONY: manpages
+manpages: _output/bin/limactl$(exe)
+	@mkdir -p _output/share/man/man1
+	$< generate-man _output/share/man/man1
+
 .PHONY: diagrams
 diagrams: docs/lima-sequence-diagram.png
 docs/lima-sequence-diagram.png: docs/images/lima-sequence-diagram.puml
@@ -138,6 +143,8 @@ uninstall:
 		"$(DEST)/bin/docker.lima" \
 		"$(DEST)/bin/podman.lima" \
 		"$(DEST)/bin/kubectl.lima" \
+		"$(DEST)/share/man/man1/lima.1" \
+		"$(DEST)/share/man/man1/limactl"*".1" \
 		"$(DEST)/share/lima" "$(DEST)/share/doc/lima"
 	if [ "$$(readlink "$(DEST)/bin/nerdctl")" = "nerdctl.lima" ]; then rm "$(DEST)/bin/nerdctl"; fi
 	if [ "$$(readlink "$(DEST)/bin/apptainer")" = "apptainer.lima" ]; then rm "$(DEST)/bin/apptainer"; fi

cmd/limactl/genman.go

@@ -0,0 +1,53 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+
+	"github.com/cpuguy83/go-md2man/v2/md2man"
+	"github.com/sirupsen/logrus"
+	"github.com/spf13/cobra"
+	"github.com/spf13/cobra/doc"
+)
+
+func newGenManCommand() *cobra.Command {
+	genmanCommand := &cobra.Command{
+		Use:    "generate-man DIR",
+		Short:  "Generate manual pages",
+		Args:   WrapArgsError(cobra.MinimumNArgs(1)),
+		RunE:   genmanAction,
+		Hidden: true,
+	}
+	return genmanCommand
+}
+
+func genmanAction(cmd *cobra.Command, args []string) error {
+	dir := args[0]
+	logrus.Infof("Generating man %q", dir)
+	// lima(1)
+	filePath := filepath.Join(dir, "lima.1")
+	md := "LIMA 1\n======" + `
+# NAME
+lima - ` + cmd.Root().Short + `
+# SYNOPSIS
+**lima** [_COMMAND_...]
+# DESCRIPTION
+lima is an alias for "limactl shell default".
+The instance name ("default") can be changed by specifying $LIMA_INSTANCE.
+
+The shell and initial workdir inside the instance can be specified via $LIMA_SHELL
+and $LIMA_WORKDIR.
+# SEE ALSO
+**limactl**(1)
+`
+	out := md2man.Render([]byte(md))
+	if err := os.WriteFile(filePath, out, 0644); err != nil {
+		return err
+	}
+	// limactl(1)
+	header := &doc.GenManHeader{
+		Title:   "LIMACTL",
+		Section: "1",
+	}
+	return doc.GenManTree(cmd.Root(), header, dir)
+}

cmd/limactl/main.go

@@ -52,8 +52,9 @@ func newApp() *cobra.Command {
   $ limactl stop
 
   See also example YAMLs: %s`, examplesDir),
-		SilenceUsage:  true,
-		SilenceErrors: true,
+		SilenceUsage:      true,
+		SilenceErrors:     true,
+		DisableAutoGenTag: true,
 	}
 	rootCmd.PersistentFlags().String("log-level", "", "Set the logging level [trace, debug, info, warn, error]")
 	rootCmd.PersistentFlags().Bool("debug", false, "debug mode")
@@ -82,7 +83,7 @@ func newApp() *cobra.Command {
 			formatter.ForceColors = true
 			logrus.StandardLogger().SetFormatter(formatter)
 		}
-		if os.Geteuid() == 0 {
+		if os.Geteuid() == 0 && cmd.Name() != "generate-man" {
 			return errors.New("must not run as the root")
 		}
 		// Make sure either $HOME or $LIMA_HOME is defined, so we don't need
@@ -110,6 +111,7 @@ func newApp() *cobra.Command {
 		newFactoryResetCommand(),
 		newDiskCommand(),
 		newUsernetCommand(),
+		newGenManCommand(),
 	)
 	return rootCmd
 }

go.mod

@@ -12,6 +12,7 @@ require (
 	github.com/containerd/continuity v0.3.0
 	github.com/containers/gvisor-tap-vsock v0.6.1
 	github.com/coreos/go-semver v0.3.1
+	github.com/cpuguy83/go-md2man/v2 v2.0.2
 	github.com/cyphar/filepath-securejoin v0.2.3
 	github.com/digitalocean/go-qemu v0.0.0-20210326154740-ac9e0b687001
 	github.com/diskfs/go-diskfs v1.3.0
@@ -96,6 +97,7 @@ require (
 	github.com/pkg/errors v0.9.1 // indirect
 	github.com/pkg/sftp v1.13.5 // indirect
 	github.com/rivo/uniseg v0.2.0 // indirect
+	github.com/russross/blackfriday/v2 v2.1.0 // indirect
 	github.com/spf13/pflag v1.0.5 // indirect
 	github.com/u-root/uio v0.0.0-20210528114334-82958018845c // indirect
 	go.uber.org/atomic v1.7.0 // indirect

go.sum

@@ -120,6 +120,7 @@ github.com/coreos/go-systemd/v22 v22.0.0/go.mod h1:xO0FLkIi5MaZafQlIrOotqXZ90ih+
 github.com/coreos/go-systemd/v22 v22.1.0/go.mod h1:xO0FLkIi5MaZafQlIrOotqXZ90ih+1atmu1JpKERPPk=
 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/creack/pty v1.1.9/go.mod h1:oKZEueFk5CKHvIhNR5MUki03XCEU+Q6VDXinZuGJ33E=
 github.com/creack/pty v1.1.17 h1:QeVUsEDNrLBW4tMgZHvxy18sKtr6VI492kBhUfhDJNI=
@@ -473,6 +474,7 @@ github.com/rivo/uniseg v0.2.0/go.mod h1:J6wj4VEh+S6ZtnVlnTBMWIodfgj8LQOQFoIToxlJ
 github.com/rogpeppe/go-charset v0.0.0-20180617210344-2471d30d28b4/go.mod h1:qgYeAmZ5ZIpBWTGllZSQnw97Dj+woV0toclVaRGI8pc=
 github.com/rogpeppe/go-internal v1.3.0/go.mod h1:M8bDsm7K2OlrFYOpmOWEs/qY81heoFRclV5y23lUDJ4=
 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/go-glob v1.0.0/go.mod h1:807d1WSdnB0XRJzKNil9Om6lcp/3a0v4qIHxIXzX/Yc=
 github.com/sethvargo/go-password v0.2.0 h1:BTDl4CC/gjf/axHMaDQtw507ogrXLci6XRiLc7i/UHI=