Automatically generate markdown pages from bor CLI

Adding a script that can automatically generate markdown pages from bor
CLI, so we can avoid copy-pasting helper strings whenever a flag is created,
deleted, or modified.

CLI docs could be generated with command `make docs`.

Makefile

@@ -2,7 +2,11 @@
 # with Go source code. If you know what GOPATH is then you probably
 # don't need to bother with make.
 
-.PHONY: geth android ios evm all test clean
+.PHONY: geth android ios geth-cross evm all test clean docs
+.PHONY: geth-linux geth-linux-386 geth-linux-amd64 geth-linux-mips64 geth-linux-mips64le
+.PHONY: geth-linux-arm geth-linux-arm-5 geth-linux-arm-6 geth-linux-arm-7 geth-linux-arm64
+.PHONY: geth-darwin geth-darwin-386 geth-darwin-amd64
+.PHONY: geth-windows geth-windows-386 geth-windows-amd64
 
 GOBIN = ./build/bin
 GO ?= latest
@@ -43,6 +47,9 @@ test:
 lint: ## Run linters.
  $(GORUN) build/ci.go lint
 
+docs:
+ $(GORUN) cmd/clidoc/main.go -d ./docs/cli
+
 clean:
  env GO111MODULE=on go clean -cache
  rm -fr build/_workspace/pkg/ $(GOBIN)/*

cmd/clidoc/main.go

@@ -0,0 +1,71 @@
+package main
+
+import (
+ "flag"
+ "log"
+ "os"
+ "path/filepath"
+ "sort"
+ "strings"
+
+ "github.com/ethereum/go-ethereum/internal/cli"
+)
+
+const (
+ DefaultDir string = "./docs/cli"
+ DefaultMainPage string = "README.md"
+)
+
+func main() {
+
+ commands := cli.Commands()
+
+ dest := flag.String("d", DefaultDir, "Destination directory where the docs will be generated")
+ flag.Parse()
+
+ dirPath := filepath.Join(".", *dest)
+ if err := os.MkdirAll(dirPath, os.ModePerm); err != nil {
+ log.Fatalln("Failed to create directory.", err)
+ }
+
+ mainPage := []string{
+ "# Bor command line interface",
+ "## Commands",
+ }
+
+ keys := make([]string, len(commands))
+ i := 0
+ for k := range commands {
+ keys[i] = k
+ i++
+ }
+ sort.Strings(keys)
+
+ for _, name := range keys {
+ cmd, err := commands[name]()
+ if err != nil {
+ log.Fatalf("Error occurred when inspecting bor command %s: %s", name, err)
+ }
+
+ fileName := strings.ReplaceAll(name, " ", "_") + ".md"
+
+ overwriteFile(filepath.Join(dirPath, fileName), cmd.MarkDown())
+ mainPage = append(mainPage, "- [```"+name+"```](./"+fileName+")")
+ }
+
+ overwriteFile(filepath.Join(dirPath, DefaultMainPage), strings.Join(mainPage, "\n\n"))
+
+ os.Exit(0)
+}
+
+func overwriteFile(filePath string, text string) {
+ log.Printf("Writing to page: %s\n", filePath)
+ f, err := os.Create(filePath)
+ if err != nil {
+ log.Fatalln(err)
+ }
+ f.WriteString(text)
+ if err := f.Close(); err != nil {
+ log.Fatalln(err)
+ }
+}

docs/cli/README.md

@@ -1,24 +1,27 @@
-
-# Command line interface
+# Bor command line interface
 
 ## Commands
 
-- [```server```](./server.md)
-
-- [```debug```](./debug.md)
-
 - [```account```](./account.md)
 
-- [```account new```](./account_new.md)
+- [```account import```](./account_import.md)
 
 - [```account list```](./account_list.md)
 
-- [```account import```](./account_import.md)
+- [```account new```](./account_new.md)
+
+- [```attach```](./attach.md)
 
 - [```chain```](./chain.md)
 
 - [```chain sethead```](./chain_sethead.md)
 
+- [```chain watch```](./chain_watch.md)
+
+- [```debug```](./debug.md)
+
+- [```fingerprint```](./fingerprint.md)
+
 - [```peers```](./peers.md)
 
 - [```peers add```](./peers_add.md)
@@ -29,8 +32,8 @@
 
 - [```peers status```](./peers_status.md)
 
-- [```status```](./status.md)
+- [```server```](./server.md)
 
-- [```chain watch```](./chain_watch.md)
+- [```status```](./status.md)
 
-- [```version```](./version.md)
+- [```version```](./version.md)

docs/cli/account.md

@@ -1,4 +1,3 @@
-
 # Account
 
 The ```account``` command groups actions to interact with accounts:
@@ -7,4 +6,4 @@ The ```account``` command groups actions to interact with accounts:
 
 - [```account list```](./account_list.md): List the wallets in the Bor client.
 
-- [```account import```](./account_import.md): Import an account to the Bor client.
+- [```account import```](./account_import.md): Import an account to the Bor client.

docs/cli/account_import.md

@@ -1,4 +1,9 @@
-
 # Account import
 
 The ```account import``` command imports an account in Json format to the Bor data directory.
+
+## Options
+
+- ```datadir```: Path of the data directory to store information
+
+- ```keystore```: Path of the data directory to store information

docs/cli/account_list.md

@@ -1,4 +1,9 @@
-
 # Account list
 
-The ```account list``` command lists all the accounts in the Bor data directory.
+The `account list` command lists all the accounts in the Bor data directory.
+
+## Options
+
+- ```datadir```: Path of the data directory to store information
+
+- ```keystore```: Path of the data directory to store information

docs/cli/account_new.md

@@ -1,4 +1,9 @@
-
 # Account new
 
-The ```account new``` command creates a new local account file on the Bor data directory. Bor should not be running to execute this command.
+The `account new` command creates a new local account file on the Bor data directory. Bor should not be running to execute this command.
+
+## Options
+
+- ```datadir```: Path of the data directory to store information
+
+- ```keystore```: Path of the data directory to store information

docs/cli/attach.md

@@ -0,0 +1,11 @@
+# Attach
+
+Connect to remote Bor IPC console.
+
+## Options
+
+- ```exec```: Command to run in remote console
+
+- ```preload```: Comma separated list of JavaScript files to preload into the console
+
+- ```jspath```: JavaScript root path for `loadScript`

docs/cli/chain.md

@@ -1,6 +1,7 @@
-
 # Chain
 
 The ```chain``` command groups actions to interact with the blockchain in the client:
 
 - [```chain sethead```](./chain_sethead.md): Set the current chain to a certain block.
+
+- [```chain watch```](./chain_watch.md): Watch the chainHead, reorg and fork events in real-time.

docs/cli/chain_sethead.md

@@ -1,4 +1,3 @@
-
 # Chain sethead
 
 The ```chain sethead <number>``` command sets the current chain to a certain block.
@@ -9,4 +8,6 @@ The ```chain sethead <number>``` command sets the current chain to a certain blo
 
 ## Options
 
-- ```yes```: Force set head.
+- ```address```: Address of the grpc endpoint
+
+- ```yes```: Force set head

docs/cli/chain_watch.md

@@ -1,3 +1,3 @@
 # Chain watch
 
-The ```chain watch``` command is used to view the chainHead, reorg and fork events in real-time.
+The ```chain watch``` command is used to view the chainHead, reorg and fork events in real-time.

docs/cli/debug.md

@@ -1,22 +1,23 @@
-
 # Debug
 
 The ```bor debug``` command takes a debug dump of the running client.
 
 ## Options
 
-- ```seconds```: Number of seconds to trace cpu and traces.
+- ```address```: Address of the grpc endpoint
+
+- ```seconds```: seconds to trace
 
-- ```output```: Output directory for the data dump.
+- ```output```: Output directory
 
 ## Examples
 
 By default it creates a tar.gz file with the output:
 
 ```
 $ bor debug
-Starting debugger... 
- 
+Starting debugger...
+
 Created debug archive: bor-debug-2021-10-26-073819Z.tar.gz
 ```
 
@@ -27,4 +28,4 @@ $ bor debug --output data
 Starting debugger...
 
 Created debug directory: data/bor-debug-2021-10-26-075437Z
-```
+```

docs/cli/fingerprint.md

@@ -0,0 +1,3 @@
+# Fingerprint
+
+Display the system fingerprint

docs/cli/peers.md

@@ -1,4 +1,3 @@
-
 # Peers
 
 The ```peers``` command groups actions to interact with peers:
@@ -9,4 +8,4 @@ The ```peers``` command groups actions to interact with peers:
 
 - [```peers remove```](./peers_remove.md): Disconnects the local client from a connected peer if exists.
 
-- [```peers status```](./peers_status.md): Display the status of a peer by its id.
+- [```peers status```](./peers_status.md): Display the status of a peer by its id.

docs/cli/peers_add.md

@@ -1,8 +1,9 @@
-
 # Peers add
 
 The ```peers add <enode>``` command joins the local client to another remote peer.
 
-## Arguments
+## Options
+
+- ```address```: Address of the grpc endpoint
 
-- ```trusted```: Whether the peer is added as a trusted peer.
+- ```trusted```: Add the peer as a trusted

docs/cli/peers_list.md

@@ -1,4 +1,7 @@
-
-# Peers list
+# Peers add
 
 The ```peers list``` command lists the connected peers.
+
+## Options
+
+- ```address```: Address of the grpc endpoint

docs/cli/peers_remove.md

@@ -1,4 +1,9 @@
-
 # Peers remove
 
 The ```peers remove <enode>``` command disconnects the local client from a connected peer if exists.
+
+## Options
+
+- ```address```: Address of the grpc endpoint
+
+- ```trusted```: Add the peer as a trusted

docs/cli/peers_status.md

@@ -1,4 +1,7 @@
-
 # Peers status
 
 The ```peers status <peer id>``` command displays the status of a peer by its id.
+
+## Options
+
+- ```address```: Address of the grpc endpoint