feat(docs): generate cli docs directly from the struct

CHANGELOG.md

@@ -3,6 +3,7 @@
 # UNRELEASED
 
 - Add Market PendingProposals API / CLI. ([filecoin-project/lotus#12724](https://github.com/filecoin-project/lotus/pull/12724))
+- Generate the cli docs directly from the code instead compiling and executing binaries' `help` output. ([filecoin-project/lotus#12717](https://github.com/filecoin-project/lotus/pull/12717))
 
 ## Improvements
 

Makefile

@@ -348,11 +348,8 @@ snap: lotus lotus-miner lotus-worker
 	snapcraft
 	# snapcraft upload ./lotus_*.snap
 
-# separate from gen because it needs binaries
-docsgen-cli: lotus lotus-miner lotus-worker
+docsgen-cli:
 	$(GOCC) run ./scripts/docsgen-cli
-	./lotus config default > documentation/en/default-lotus-config.toml
-	./lotus-miner config default > documentation/en/default-lotus-miner-config.toml
 .PHONY: docsgen-cli
 
 print-%:

cli/auth.go

@@ -12,123 +12,129 @@ import (
 	"github.com/filecoin-project/lotus/node/repo"
 )
 
-var AuthCmd = &cli.Command{
-	Name:  "auth",
-	Usage: "Manage RPC permissions",
-	Subcommands: []*cli.Command{
-		AuthCreateAdminToken,
-		AuthApiInfoToken,
-	},
+func AuthCmd() *cli.Command {
+	return &cli.Command{
+		Name:  "auth",
+		Usage: "Manage RPC permissions",
+		Subcommands: []*cli.Command{
+			AuthCreateAdminTokenCmd(),
+			AuthApiInfoTokenCmd(),
+		},
+	}
 }
 
-var AuthCreateAdminToken = &cli.Command{
-	Name:  "create-token",
-	Usage: "Create token",
-	Flags: []cli.Flag{
-		&cli.StringFlag{
-			Name:  "perm",
-			Usage: "permission to assign to the token, one of: read, write, sign, admin",
+func AuthCreateAdminTokenCmd() *cli.Command {
+	return &cli.Command{
+		Name:  "create-token",
+		Usage: "Create token",
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:  "perm",
+				Usage: "permission to assign to the token, one of: read, write, sign, admin",
+			},
 		},
-	},
-
-	Action: func(cctx *cli.Context) error {
-		napi, closer, err := GetAPI(cctx)
-		if err != nil {
-			return err
-		}
-		defer closer()
-
-		ctx := ReqContext(cctx)
-
-		if !cctx.IsSet("perm") {
-			return xerrors.New("--perm flag not set")
-		}
-
-		perm := cctx.String("perm")
-		idx := 0
-		for i, p := range api.AllPermissions {
-			if auth.Permission(perm) == p {
-				idx = i + 1
+
+		Action: func(cctx *cli.Context) error {
+			napi, closer, err := GetAPI(cctx)
+			if err != nil {
+				return err
+			}
+			defer closer()
+
+			ctx := ReqContext(cctx)
+
+			if !cctx.IsSet("perm") {
+				return xerrors.New("--perm flag not set")
+			}
+
+			perm := cctx.String("perm")
+			idx := 0
+			for i, p := range api.AllPermissions {
+				if auth.Permission(perm) == p {
+					idx = i + 1
+				}
 			}
-		}
 
-		if idx == 0 {
-			return fmt.Errorf("--perm flag has to be one of: %s", api.AllPermissions)
-		}
+			if idx == 0 {
+				return fmt.Errorf("--perm flag has to be one of: %s", api.AllPermissions)
+			}
 
-		// slice on [:idx] so for example: 'sign' gives you [read, write, sign]
-		token, err := napi.AuthNew(ctx, api.AllPermissions[:idx])
-		if err != nil {
-			return err
-		}
+			// slice on [:idx] so for example: 'sign' gives you [read, write, sign]
+			token, err := napi.AuthNew(ctx, api.AllPermissions[:idx])
+			if err != nil {
+				return err
+			}
 
-		// TODO: Log in audit log when it is implemented
+			// TODO: Log in audit log when it is implemented
 
-		fmt.Println(string(token))
-		return nil
-	},
+			fmt.Println(string(token))
+			return nil
+		},
+	}
 }
 
-var AuthApiInfoToken = &cli.Command{
-	Name:  "api-info",
-	Usage: "Get token with API info required to connect to this node",
-	Flags: []cli.Flag{
-		&cli.StringFlag{
-			Name:  "perm",
-			Usage: "permission to assign to the token, one of: read, write, sign, admin",
+func AuthApiInfoTokenCmd() *cli.Command {
+	return &cli.Command{
+		Name:  "api-info",
+		Usage: "Get token with API info required to connect to this node",
+		Flags: []cli.Flag{
+			&cli.StringFlag{
+				Name:  "perm",
+				Usage: "permission to assign to the token, one of: read, write, sign, admin",
+			},
 		},
-	},
-
-	Action: func(cctx *cli.Context) error {
-		napi, closer, err := GetAPI(cctx)
-		if err != nil {
-			return err
-		}
-		defer closer()
-
-		ctx := ReqContext(cctx)
-
-		if !cctx.IsSet("perm") {
-			return xerrors.New("--perm flag not set, use with one of: read, write, sign, admin")
-		}
-
-		perm := cctx.String("perm")
-		idx := 0
-		for i, p := range api.AllPermissions {
-			if auth.Permission(perm) == p {
-				idx = i + 1
+
+		Action: func(cctx *cli.Context) error {
+			napi, closer, err := GetAPI(cctx)
+			if err != nil {
+				return err
+			}
+			defer closer()
+
+			ctx := ReqContext(cctx)
+
+			if !cctx.IsSet("perm") {
+				return xerrors.New("--perm flag not set, use with one of: read, write, sign, admin")
 			}
-		}
-
-		if idx == 0 {
-			return fmt.Errorf("--perm flag has to be one of: %s", api.AllPermissions)
-		}
-
-		// slice on [:idx] so for example: 'sign' gives you [read, write, sign]
-		token, err := napi.AuthNew(ctx, api.AllPermissions[:idx])
-		if err != nil {
-			return err
-		}
-
-		ti, ok := cctx.App.Metadata["repoType"]
-		if !ok {
-			log.Errorf("unknown repo type, are you sure you want to use GetCommonAPI?")
-			ti = repo.FullNode
-		}
-		t, ok := ti.(repo.RepoType)
-		if !ok {
-			log.Errorf("repoType type does not match the type of repo.RepoType")
-		}
-
-		ainfo, err := GetAPIInfo(cctx, t)
-		if err != nil {
-			return xerrors.Errorf("could not get API info for %s: %w", t, err)
-		}
-
-		// TODO: Log in audit log when it is implemented
-
-		currentEnv, _, _ := t.APIInfoEnvVars()
-		fmt.Printf("%s=%s:%s\n", currentEnv, string(token), ainfo.Addr)
-		return nil
-	},
+
+			perm := cctx.String("perm")
+			idx := 0
+			for i, p := range api.AllPermissions {
+				if auth.Permission(perm) == p {
+					idx = i + 1
+				}
+			}
+
+			if idx == 0 {
+				return fmt.Errorf("--perm flag has to be one of: %s", api.AllPermissions)
+			}
+
+			// slice on [:idx] so for example: 'sign' gives you [read, write, sign]
+			token, err := napi.AuthNew(ctx, api.AllPermissions[:idx])
+			if err != nil {
+				return err
+			}
+
+			ti, ok := cctx.App.Metadata["repoType"]
+			if !ok {
+				log.Errorf("unknown repo type, are you sure you want to use GetCommonAPI?")
+				ti = repo.FullNode
+			}
+			t, ok := ti.(repo.RepoType)
+			if !ok {
+				log.Errorf("repoType type does not match the type of repo.RepoType")
+			}
+
+			ainfo, err := GetAPIInfo(cctx, t)
+			if err != nil {
+				return xerrors.Errorf("could not get API info for %s: %w", t, err)
+			}
+
+			// TODO: Log in audit log when it is implemented
+
+			currentEnv, _, _ := t.APIInfoEnvVars()
+			fmt.Printf("%s=%s:%s\n", currentEnv, string(token), ainfo.Addr)
+			return nil
+		},
+	}
 }

cli/clicommands/cmd.go

@@ -13,19 +13,19 @@ var Commands = []*cli.Command{
 	lcli.WithCategory("basic", lcli.MultisigCmd),
 	lcli.WithCategory("basic", lcli.FilplusCmd),
 	lcli.WithCategory("basic", lcli.PaychCmd),
-	lcli.WithCategory("developer", lcli.AuthCmd),
+	lcli.WithCategory("developer", lcli.AuthCmd()),
 	lcli.WithCategory("developer", lcli.MpoolCmd),
 	lcli.WithCategory("developer", StateCmd),
 	lcli.WithCategory("developer", lcli.ChainCmd),
-	lcli.WithCategory("developer", lcli.LogCmd),
-	lcli.WithCategory("developer", lcli.WaitApiCmd),
-	lcli.WithCategory("developer", lcli.FetchParamCmd),
+	lcli.WithCategory("developer", lcli.LogCmd()),
+	lcli.WithCategory("developer", lcli.WaitApiCmd()),
+	lcli.WithCategory("developer", lcli.FetchParamCmd()),
 	lcli.WithCategory("developer", lcli.EvmCmd),
 	lcli.WithCategory("developer", lcli.IndexCmd),
 	lcli.WithCategory("network", lcli.NetCmd),
 	lcli.WithCategory("network", lcli.SyncCmd),
 	lcli.WithCategory("network", lcli.F3Cmd),
 	lcli.WithCategory("status", lcli.StatusCmd),
-	lcli.PprofCmd,
-	lcli.VersionCmd,
+	lcli.PprofCmd(),
+	lcli.VersionCmd(),
 }

cli/cmd.go

@@ -57,12 +57,12 @@ var GetStorageMinerAPI = cliutil.GetStorageMinerAPI
 var GetWorkerAPI = cliutil.GetWorkerAPI
 
 var CommonCommands = []*cli.Command{
-	AuthCmd,
-	LogCmd,
-	WaitApiCmd,
-	FetchParamCmd,
-	PprofCmd,
-	VersionCmd,
+	AuthCmd(),
+	LogCmd(),
+	WaitApiCmd(),
+	FetchParamCmd(),
+	PprofCmd(),
+	VersionCmd(),
 }
 
 func WithCategory(cat string, cmd *cli.Command) *cli.Command {