Merge pull request #6145 from filecoin-project/feat/cli-doc-gen

Generate CLI docs

.circleci/config.yml

@@ -436,7 +436,7 @@ jobs:
       - run:
           command: "! go fmt ./... 2>&1 | read"
 
-  cbor-gen-check:
+  gen-check:
     executor: golang
     steps:
       - install-deps
@@ -444,7 +444,10 @@ jobs:
       - run: make deps
       - run: go install golang.org/x/tools/cmd/goimports
       - run: go install github.com/hannahhoward/cbor-gen-for
-      - run: make type-gen
+      - run: make gen
+      - run: git --no-pager diff
+      - run: git --no-pager diff --quiet
+      - run: make docsgen-cli
       - run: git --no-pager diff
       - run: git --no-pager diff --quiet
 
@@ -701,7 +704,7 @@ workflows:
           concurrency: "16"   # expend all docker 2xlarge CPUs.
       - mod-tidy-check
       - gofmt
-      - cbor-gen-check
+      - gen-check
       - docs-check
       - test:
           codecov-upload: true

Makefile

@@ -368,7 +368,13 @@ docsgen-openrpc-worker: docsgen-openrpc-bin
 .PHONY: docsgen docsgen-md-bin docsgen-openrpc-bin
 
 gen: type-gen method-gen docsgen api-gen
+	@echo ">>> IF YOU'VE MODIFIED THE CLI, REMEMBER TO ALSO MAKE docsgen-cli"
 .PHONY: gen
 
+# separate from gen because it needs binaries
+docsgen-cli: lotus lotus-miner lotus-worker
+	python ./scripts/generate-lotus-cli.py
+.PHONY: docsgen-cli
+
 print-%:
 	@echo $*=$($*)

build/version.go

@@ -1,5 +1,7 @@
 package build
 
+import "os"
+
 var CurrentCommit string
 var BuildType int
 
@@ -32,5 +34,9 @@ func buildType() string {
 const BuildVersion = "1.11.0-dev"
 
 func UserVersion() string {
+	if os.Getenv("LOTUS_VERSION_IGNORE_COMMIT") == "1" {
+		return BuildVersion
+	}
+
 	return BuildVersion + buildType() + CurrentCommit
 }

documentation/en/cli-lotus-worker.md

@@ -0,0 +1,171 @@
+# lotus-worker
+```
+NAME:
+   lotus-worker - Remote miner worker
+
+USAGE:
+   lotus-worker [global options] command [command options] [arguments...]
+
+VERSION:
+   1.11.0-dev
+
+COMMANDS:
+   run         Start lotus worker
+   info        Print worker info
+   storage     manage sector storage
+   set         Manage worker settings
+   wait-quiet  Block until all running tasks exit
+   tasks       Manage task processing
+   help, h     Shows a list of commands or help for one command
+
+GLOBAL OPTIONS:
+   --worker-repo value, --workerrepo value  Specify worker repo path. flag workerrepo and env WORKER_PATH are DEPRECATION, will REMOVE SOON (default: "~/.lotusworker") [$LOTUS_WORKER_PATH, $WORKER_PATH]
+   --miner-repo value, --storagerepo value  Specify miner repo path. flag storagerepo and env LOTUS_STORAGE_PATH are DEPRECATION, will REMOVE SOON (default: "~/.lotusminer") [$LOTUS_MINER_PATH, $LOTUS_STORAGE_PATH]
+   --enable-gpu-proving                     enable use of GPU for mining operations (default: true)
+   --help, -h                               show help (default: false)
+   --version, -v                            print the version (default: false)
+```
+
+## lotus-worker run
+```
+NAME:
+   lotus-worker run - Start lotus worker
+
+USAGE:
+   lotus-worker run [command options] [arguments...]
+
+OPTIONS:
+   --listen value                host address and port the worker api will listen on (default: "0.0.0.0:3456")
+   --no-local-storage            don't use storageminer repo for sector storage (default: false)
+   --no-swap                     don't use swap (default: false)
+   --addpiece                    enable addpiece (default: true)
+   --precommit1                  enable precommit1 (32G sectors: 1 core, 128GiB Memory) (default: true)
+   --unseal                      enable unsealing (32G sectors: 1 core, 128GiB Memory) (default: true)
+   --precommit2                  enable precommit2 (32G sectors: all cores, 96GiB Memory) (default: true)
+   --commit                      enable commit (32G sectors: all cores or GPUs, 128GiB Memory + 64GiB swap) (default: true)
+   --parallel-fetch-limit value  maximum fetch operations to run in parallel (default: 5)
+   --timeout value               used when 'listen' is unspecified. must be a valid duration recognized by golang's time.ParseDuration function (default: "30m")
+   --help, -h                    show help (default: false)
+   
+```
+
+## lotus-worker info
+```
+NAME:
+   lotus-worker info - Print worker info
+
+USAGE:
+   lotus-worker info [command options] [arguments...]
+
+OPTIONS:
+   --help, -h  show help (default: false)
+   
+```
+
+## lotus-worker storage
+```
+NAME:
+   lotus-worker storage - manage sector storage
+
+USAGE:
+   lotus-worker storage command [command options] [arguments...]
+
+COMMANDS:
+   attach   attach local storage path
+   help, h  Shows a list of commands or help for one command
+
+OPTIONS:
+   --help, -h     show help (default: false)
+   --version, -v  print the version (default: false)
+   
+```
+
+### lotus-worker storage attach
+```
+NAME:
+   lotus-worker storage attach - attach local storage path
+
+USAGE:
+   lotus-worker storage attach [command options] [arguments...]
+
+OPTIONS:
+   --init               initialize the path first (default: false)
+   --weight value       (for init) path weight (default: 10)
+   --seal               (for init) use path for sealing (default: false)
+   --store              (for init) use path for long-term storage (default: false)
+   --max-storage value  (for init) limit storage space for sectors (expensive for very large paths!)
+   --help, -h           show help (default: false)
+   
+```
+
+## lotus-worker set
+```
+NAME:
+   lotus-worker set - Manage worker settings
+
+USAGE:
+   lotus-worker set [command options] [arguments...]
+
+OPTIONS:
+   --enabled   enable/disable new task processing (default: true)
+   --help, -h  show help (default: false)
+   
+```
+
+## lotus-worker wait-quiet
+```
+NAME:
+   lotus-worker wait-quiet - Block until all running tasks exit
+
+USAGE:
+   lotus-worker wait-quiet [command options] [arguments...]
+
+OPTIONS:
+   --help, -h  show help (default: false)
+   
+```
+
+## lotus-worker tasks
+```
+NAME:
+   lotus-worker tasks - Manage task processing
+
+USAGE:
+   lotus-worker tasks command [command options] [arguments...]
+
+COMMANDS:
+   enable   Enable a task type
+   disable  Disable a task type
+   help, h  Shows a list of commands or help for one command
+
+OPTIONS:
+   --help, -h     show help (default: false)
+   --version, -v  print the version (default: false)
+   
+```
+
+### lotus-worker tasks enable
+```
+NAME:
+   lotus-worker tasks enable - Enable a task type
+
+USAGE:
+   lotus-worker tasks enable [command options] [UNS|C2|PC2|PC1|AP]
+
+OPTIONS:
+   --help, -h  show help (default: false)
+   
+```
+
+### lotus-worker tasks disable
+```
+NAME:
+   lotus-worker tasks disable - Disable a task type
+
+USAGE:
+   lotus-worker tasks disable [command options] [UNS|C2|PC2|PC1|AP]
+
+OPTIONS:
+   --help, -h  show help (default: false)
+   
+```

scripts/generate-lotus-cli.py

@@ -0,0 +1,52 @@
+#!/usr/bin/env python
+# Generate lotus command lines documents as text and markdown in folder "lotus/documentation/en".
+# Python 2.7
+
+import os
+
+
+def generate_lotus_cli(prog):
+    output_folder = 'documentation/en'
+    md_file = open('%s/cli-%s.md' % (output_folder, prog), 'w')  # set the name of md output
+
+    def get_cmd_recursively(cur_cmd):
+        depth = cur_cmd.count(' ')
+        md_file.writelines(('\n' * min(depth, 1)) + ('#' * depth) + '# ' + cur_cmd[2:] + '\n')
+
+        cmd_flag = False
+
+        print('> ' + cur_cmd)
+        cmd_help_output = os.popen(cur_cmd + ' -h')
+        cmd_help_output_lines = cmd_help_output.readlines()
+
+        md_file.writelines('```\n')
+        md_file.writelines(cmd_help_output_lines)
+        md_file.writelines('```\n')
+
+        for line in cmd_help_output_lines:
+            try:
+                line = line.strip()
+                if line == 'COMMANDS:':
+                    cmd_flag = True
+                if cmd_flag is True and line == '':
+                    cmd_flag = False
+                if cmd_flag is True and line[-1] != ':' and 'help, h' not in line:
+                    gap_pos = 0
+                    sub_cmd = line
+                    if ' ' in line:
+                        gap_pos = sub_cmd.index('  ')
+                    if gap_pos:
+                        sub_cmd = cur_cmd + ' ' + sub_cmd[:gap_pos]
+                    get_cmd_recursively(sub_cmd)
+            except Exception as e:
+                print('Fail to deal with "%s" with error:\n%s' % (line, e))
+
+    get_cmd_recursively('./' + prog)
+    md_file.close()
+
+
+if __name__ == "__main__":
+    os.putenv("LOTUS_VERSION_IGNORE_COMMIT", "1")
+    generate_lotus_cli('lotus')
+    generate_lotus_cli('lotus-miner')
+    generate_lotus_cli('lotus-worker')