Group CLI options into sections in help docs (#2272)

### What
Move the doc-gen binary code into its own crate, separate from the
soroban-cli crate, and have it be dependent on the unmerged pull request
to clap-markdown that adds support for grouping cli options:
- ConnorGray/clap-markdown#48

### Why
The grouped options experience is a massive improvement. It makes the
help documentation easier to scan and understand. It's the way the
options are organised on the command line and the help markdown
documentation should follow suite. While the pull request adds the
feature upstream, the pull request hasn't been accepted yet.

The clap-markdown dependency isn't needed for the stellar-cli other than
doc-gen, so it is in any case good to get the dependency outside of the
soroban-cli crate, so that it isn't downloaded by cargo everytime
someone installs the stellar-cli. Moving doc-gen into its own crate is
trivial because the soroban-cli is designed to be embedded, and achieves
that. Additionally because the doc-gen crate does not need to be
published it can reference the unreleased pull request without issue.

Author: leighmcculloch

.github/workflows/dependency-check.yml

@@ -3,6 +3,7 @@ resolver = "2"
 members = [
     "cmd/stellar-cli",
     "cmd/soroban-cli",
+    "cmd/doc-gen",
     "cmd/crates/*",
     "cmd/crates/soroban-test/tests/fixtures/test-wasms/*",
     "cmd/crates/soroban-test/tests/fixtures/hello",

Cargo.lock

@@ -44,7 +44,7 @@ build-test-wasms:
 build-test: build-test-wasms install
 
 docs:
-	cargo run --bin doc-gen
+	cargo run --package doc-gen
 	./node_modules/.bin/prettier --write --log-level warn FULL_HELP_DOCS.md
 
 test: build-test

Cargo.toml

@@ -0,0 +1,17 @@
+[package]
+name = "doc-gen"
+description = "Stellar CLI generator of markdown help documentation"
+homepage = "https://github.com/stellar/stellar-cli"
+repository = "https://github.com/stellar/stellar-cli"
+authors = ["Stellar Development Foundation <info@stellar.org>"]
+license = "Apache-2.0"
+readme = "README.md"
+version.workspace = true
+edition = "2021"
+rust-version.workspace = true
+publish = false
+
+[dependencies]
+soroban-cli = { workspace = true }
+# clap-markdown from https://github.com/ConnorGray/clap-markdown/pull/48
+clap-markdown = { version = "0.1.5", git = "https://github.com/ConnorGray/clap-markdown", rev = "42956b342cef3325d9060fc43995d595e7c8aa66" }

FULL_HELP_DOCS.md

@@ -0,0 +1,21 @@
+# Stellar CLI Documentation Generator
+
+A generator for the help documentation using clap-markdown.
+
+## Usage
+
+Run the following command from the workspace root.
+
+```
+cargo run --package doc-gen
+```
+
+The command will update the file `FULL_HELP_DOCS.md` located in the root of the workspace.
+
+Typically this command is not run directly, but in the root `Makefile` the `docs` target will run this command in conjunction with formatting the markdown.
+
+So typically run this command via make:
+
+```
+make docs
+```

Makefile

@@ -24,10 +24,6 @@ path = "src/bin/soroban.rs"
 pkg-url = "{ repo }/releases/download/v{ version }/{ name }-{ version }-{ target }{ archive-suffix }"
 bin-dir = "{ bin }{ binary-ext }"
 
-[[bin]]
-name = "doc-gen"
-path = "src/bin/doc-gen.rs"
-
 [lib]
 name = "soroban_cli"
 path = "src/lib.rs"
@@ -133,7 +129,6 @@ whoami = "1.5.2"
 serde_with = "3.11.0"
 rustc_version = "0.4.1"
 prettytable = "0.10.0"
-clap-markdown = "0.1.5"
 
 [build-dependencies]
 crate-git-revision = "0.0.6"

cmd/doc-gen/Cargo.toml

@@ -258,7 +258,10 @@ unknown-git = "deny"
 # if not specified. If it is specified but empty, no registries are allowed.
 allow-registry = ["https://github.com/rust-lang/crates.io-index"]
 # List of URLs for allowed Git repositories
-allow-git = []
+allow-git = [
+  # Only used by the unpublished doc-gen crate, temporarily until PR is merged: https://github.com/ConnorGray/clap-markdown/pull/48
+  "https://github.com/ConnorGray/clap-markdown?rev=42956b342cef3325d9060fc43995d595e7c8aa66",
+]
 
 [sources.allow-org]
 # 1 or more github.com organizations to allow git sources for