Merge branch 'main' into leighmcculloch-patch-1

FULL_HELP_DOCS.md

@@ -1,76 +1,22 @@
-# Command-Line Help for `stellar`
+# Command-Line Help for the Stellar CLI
 
 This document contains the help content for the `stellar` command-line program.
 
-**Command Overview:**
-
-* [`stellar`↴](#stellar)
-* [`stellar completion`↴](#stellar-completion)
-* [`stellar contract`↴](#stellar-contract)
-* [`stellar contract asset`↴](#stellar-contract-asset)
-* [`stellar contract asset id`↴](#stellar-contract-asset-id)
-* [`stellar contract asset deploy`↴](#stellar-contract-asset-deploy)
-* [`stellar contract bindings`↴](#stellar-contract-bindings)
-* [`stellar contract bindings json`↴](#stellar-contract-bindings-json)
-* [`stellar contract bindings rust`↴](#stellar-contract-bindings-rust)
-* [`stellar contract bindings typescript`↴](#stellar-contract-bindings-typescript)
-* [`stellar contract build`↴](#stellar-contract-build)
-* [`stellar contract extend`↴](#stellar-contract-extend)
-* [`stellar contract deploy`↴](#stellar-contract-deploy)
-* [`stellar contract fetch`↴](#stellar-contract-fetch)
-* [`stellar contract id`↴](#stellar-contract-id)
-* [`stellar contract id asset`↴](#stellar-contract-id-asset)
-* [`stellar contract id wasm`↴](#stellar-contract-id-wasm)
-* [`stellar contract init`↴](#stellar-contract-init)
-* [`stellar contract inspect`↴](#stellar-contract-inspect)
-* [`stellar contract install`↴](#stellar-contract-install)
-* [`stellar contract invoke`↴](#stellar-contract-invoke)
-* [`stellar contract optimize`↴](#stellar-contract-optimize)
-* [`stellar contract read`↴](#stellar-contract-read)
-* [`stellar contract restore`↴](#stellar-contract-restore)
-* [`stellar events`↴](#stellar-events)
-* [`stellar keys`↴](#stellar-keys)
-* [`stellar keys add`↴](#stellar-keys-add)
-* [`stellar keys address`↴](#stellar-keys-address)
-* [`stellar keys fund`↴](#stellar-keys-fund)
-* [`stellar keys generate`↴](#stellar-keys-generate)
-* [`stellar keys ls`↴](#stellar-keys-ls)
-* [`stellar keys rm`↴](#stellar-keys-rm)
-* [`stellar keys show`↴](#stellar-keys-show)
-* [`stellar xdr`↴](#stellar-xdr)
-* [`stellar xdr types`↴](#stellar-xdr-types)
-* [`stellar xdr types list`↴](#stellar-xdr-types-list)
-* [`stellar xdr types schema`↴](#stellar-xdr-types-schema)
-* [`stellar xdr guess`↴](#stellar-xdr-guess)
-* [`stellar xdr decode`↴](#stellar-xdr-decode)
-* [`stellar xdr encode`↴](#stellar-xdr-encode)
-* [`stellar xdr version`↴](#stellar-xdr-version)
-* [`stellar network`↴](#stellar-network)
-* [`stellar network add`↴](#stellar-network-add)
-* [`stellar network rm`↴](#stellar-network-rm)
-* [`stellar network ls`↴](#stellar-network-ls)
-* [`stellar network start`↴](#stellar-network-start)
-* [`stellar network stop`↴](#stellar-network-stop)
-* [`stellar network container`↴](#stellar-network-container)
-* [`stellar network container logs`↴](#stellar-network-container-logs)
-* [`stellar network container start`↴](#stellar-network-container-start)
-* [`stellar network container stop`↴](#stellar-network-container-stop)
-* [`stellar version`↴](#stellar-version)
-* [`stellar tx`↴](#stellar-tx)
-* [`stellar tx simulate`↴](#stellar-tx-simulate)
-* [`stellar cache`↴](#stellar-cache)
-* [`stellar cache clean`↴](#stellar-cache-clean)
-* [`stellar cache path`↴](#stellar-cache-path)
-* [`stellar cache actionlog`↴](#stellar-cache-actionlog)
-* [`stellar cache actionlog ls`↴](#stellar-cache-actionlog-ls)
-* [`stellar cache actionlog read`↴](#stellar-cache-actionlog-read)
-
 ## `stellar`
 
-Build, deploy, & interact with contracts; set identities to sign with; configure networks; generate keys; and more.
+With the Stellar CLI you can:
+
+- build, deploy and interact with contracts
+- set identities to sign with
+- configure networks
+- generate keys
+- more!
+
+For additional information see:
 
-Stellar Docs: https://developers.stellar.org
-CLI Full Help Docs: https://github.com/stellar/stellar-cli/tree/main/FULL_HELP_DOCS.md
+- Stellar Docs: https://developers.stellar.org
+- Smart Contract Docs: https://developers.stellar.org/docs/build/smart-contracts/overview
+- CLI Docs: https://developers.stellar.org/docs/build/smart-contracts/stellar-cli
 
 The easiest way to get started is to generate a new identity:
 
@@ -122,14 +68,12 @@ Anything after the `--` double dash (the "slop") is parsed as arguments to the c
 
 Print shell completion code for the specified shell
 
-Ensure the completion package for your shell is installed,
-e.g., bash-completion for bash.
+Ensure the completion package for your shell is installed, e.g. bash-completion for bash.
 
-To enable autocomplete in the current bash shell, run:
-  source <(stellar completion --shell bash)
+To enable autocomplete in the current bash shell, run: `source <(stellar completion --shell bash)`
+
+To enable autocomplete permanently, run: `echo "source <(stellar completion --shell bash)" >> ~/.bashrc`
 
-To enable autocomplete permanently, run:
-  echo "source <(stellar completion --shell bash)" >> ~/.bashrc
 
 **Usage:** `stellar completion --shell <SHELL>`
 
@@ -703,15 +647,11 @@ Watch the network for contract events
 * `--id <CONTRACT_IDS>` — A set of (up to 5) contract IDs to filter events on. This parameter can be passed multiple times, e.g. `--id C123.. --id C456..`, or passed with multiple parameters, e.g. `--id C123 C456`.
 
    Though the specification supports multiple filter objects (i.e. combinations of type, IDs, and topics), only one set can be specified on the command-line today, though that set can have multiple IDs/topics.
-* `--topic <TOPIC_FILTERS>` — A set of (up to 4) topic filters to filter event topics on. A single topic filter can contain 1-4 different segment filters, separated by commas, with an asterisk (* character) indicating a wildcard segment.
-
-   For example, this is one topic filter with two segments:
+* `--topic <TOPIC_FILTERS>` — A set of (up to 4) topic filters to filter event topics on. A single topic filter can contain 1-4 different segment filters, separated by commas, with an asterisk (`*` character) indicating a wildcard segment.
 
-   --topic "AAAABQAAAAdDT1VOVEVSAA==,*"
+   **Example:** topic filter with two segments: `--topic "AAAABQAAAAdDT1VOVEVSAA==,*"`
 
-   This is two topic filters with one and two segments each:
-
-   --topic "AAAABQAAAAdDT1VOVEVSAA==" --topic '*,*'
+   **Example:** two topic filters with one and two segments each: `--topic "AAAABQAAAAdDT1VOVEVSAA==" --topic '*,*'`
 
    Note that all of these topic filters are combined with the contract IDs into a single filter (i.e. combination of type, IDs, and topics).
 * `--type <EVENT_TYPE>` — Specifies which type of contract events to display
@@ -1116,9 +1056,11 @@ Start network
 
 Start a container running a Stellar node, RPC, API, and friendbot (faucet).
 
-stellar network start <NETWORK> [OPTIONS]
+`stellar network start NETWORK [OPTIONS]`
+
+By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command:
 
-By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command: docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc
+`docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc`
 
 **Usage:** `stellar network start [OPTIONS] <NETWORK>`
 
@@ -1133,7 +1075,7 @@ By default, when starting a testnet container, without any optional arguments, i
 
 * `-d`, `--docker-host <DOCKER_HOST>` — Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock
 * `-l`, `--limits <LIMITS>` — Optional argument to specify the limits for the local network only
-* `-p`, `--ports-mapping <PORTS_MAPPING>` — Argument to specify the HOST_PORT:CONTAINER_PORT mapping
+* `-p`, `--ports-mapping <PORTS_MAPPING>` — Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping
 
   Default value: `8000:8000`
 * `-t`, `--image-tag-override <IMAGE_TAG_OVERRIDE>` — Optional argument to override the default docker image tag for the given network
@@ -1201,9 +1143,11 @@ Start network
 
 Start a container running a Stellar node, RPC, API, and friendbot (faucet).
 
-stellar network start <NETWORK> [OPTIONS]
+`stellar network start NETWORK [OPTIONS]`
 
-By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command: docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc
+By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command:
+
+`docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc`
 
 **Usage:** `stellar network container start [OPTIONS] <NETWORK>`
 
@@ -1218,7 +1162,7 @@ By default, when starting a testnet container, without any optional arguments, i
 
 * `-d`, `--docker-host <DOCKER_HOST>` — Optional argument to override the default docker host. This is useful when you are using a non-standard docker host path for your Docker-compatible container runtime, e.g. Docker Desktop defaults to $HOME/.docker/run/docker.sock instead of /var/run/docker.sock
 * `-l`, `--limits <LIMITS>` — Optional argument to specify the limits for the local network only
-* `-p`, `--ports-mapping <PORTS_MAPPING>` — Argument to specify the HOST_PORT:CONTAINER_PORT mapping
+* `-p`, `--ports-mapping <PORTS_MAPPING>` — Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping
 
   Default value: `8000:8000`
 * `-t`, `--image-tag-override <IMAGE_TAG_OVERRIDE>` — Optional argument to override the default docker image tag for the given network
@@ -1352,9 +1296,3 @@ Read cached action
 
 
 
-<hr/>
-
-<small><i>
-    This document was generated automatically by
-    <a href="https://crates.io/crates/clap-markdown"><code>clap-markdown</code></a>.
-</i></small>

cmd/soroban-cli/Cargo.toml

@@ -88,7 +88,7 @@ itertools = "0.10.5"
 shlex = "1.1.0"
 sep5 = { workspace = true }
 ethnum = { workspace = true }
-clap-markdown = { version = "0.1.3", optional = true }
+clap-markdown = { version = "0.1.4", optional = true }
 which = { workspace = true, features = ["regex"] }
 strsim = "0.10.0"
 heck = "0.5.0"

cmd/soroban-cli/src/bin/doc-gen.rs

@@ -12,11 +12,14 @@ fn main() -> Result<(), DynError> {
 
 fn doc_gen() -> std::io::Result<()> {
     let out_dir = project_root();
+    let options = clap_markdown::MarkdownOptions::new()
+        .show_footer(false)
+        .show_table_of_contents(false)
+        .title("Command-Line Help for the Stellar CLI".to_string());
 
-    std::fs::write(
-        out_dir.join("FULL_HELP_DOCS.md"),
-        clap_markdown::help_markdown::<soroban_cli::Root>(),
-    )?;
+    let content = clap_markdown::help_markdown_custom::<soroban_cli::Root>(&options);
+
+    std::fs::write(out_dir.join("FULL_HELP_DOCS.md"), content)?;
 
     Ok(())
 }

cmd/soroban-cli/src/commands/completion.rs

@@ -7,14 +7,12 @@ use crate::commands::Root;
 pub const LONG_ABOUT: &str = "\
 Print shell completion code for the specified shell
 
-Ensure the completion package for your shell is installed,
-e.g., bash-completion for bash.
+Ensure the completion package for your shell is installed, e.g. bash-completion for bash.
 
-To enable autocomplete in the current bash shell, run:
-  source <(stellar completion --shell bash)
+To enable autocomplete in the current bash shell, run: `source <(stellar completion --shell bash)`
 
-To enable autocomplete permanently, run:
-  echo \"source <(stellar completion --shell bash)\" >> ~/.bashrc";
+To enable autocomplete permanently, run: `echo \"source <(stellar completion --shell bash)\" >> ~/.bashrc`
+";
 
 #[derive(Parser, Debug, Clone)]
 #[group(skip)]

cmd/soroban-cli/src/commands/events.rs

@@ -44,15 +44,11 @@ pub struct Cmd {
     contract_ids: Vec<String>,
     /// A set of (up to 4) topic filters to filter event topics on. A single
     /// topic filter can contain 1-4 different segment filters, separated by
-    /// commas, with an asterisk (* character) indicating a wildcard segment.
+    /// commas, with an asterisk (`*` character) indicating a wildcard segment.
     ///
-    /// For example, this is one topic filter with two segments:
+    /// **Example:** topic filter with two segments: `--topic "AAAABQAAAAdDT1VOVEVSAA==,*"`
     ///
-    ///     --topic "AAAABQAAAAdDT1VOVEVSAA==,*"
-    ///
-    /// This is two topic filters with one and two segments each:
-    ///
-    ///     --topic "AAAABQAAAAdDT1VOVEVSAA==" --topic '*,*'
+    /// **Example:** two topic filters with one and two segments each: `--topic "AAAABQAAAAdDT1VOVEVSAA==" --topic '*,*'`
     ///
     /// Note that all of these topic filters are combined with the contract IDs
     /// into a single filter (i.e. combination of type, IDs, and topics).

cmd/soroban-cli/src/commands/mod.rs

@@ -18,10 +18,19 @@ pub mod version;
 pub mod txn_result;
 
 pub const HEADING_RPC: &str = "Options (RPC)";
-const ABOUT: &str = "Build, deploy, & interact with contracts; set identities to sign with; configure networks; generate keys; and more.
+const ABOUT: &str = "With the Stellar CLI you can:
 
-Stellar Docs: https://developers.stellar.org
-CLI Full Help Docs: https://github.com/stellar/stellar-cli/tree/main/FULL_HELP_DOCS.md";
+- build, deploy and interact with contracts
+- set identities to sign with
+- configure networks
+- generate keys
+- more!
+
+For additional information see:
+
+- Stellar Docs: https://developers.stellar.org
+- Smart Contract Docs: https://developers.stellar.org/docs/build/smart-contracts/overview
+- CLI Docs: https://developers.stellar.org/docs/build/smart-contracts/stellar-cli";
 
 // long_about is shown when someone uses `--help`; short help when using `-h`
 const LONG_ABOUT: &str = "
@@ -38,13 +47,11 @@ Commands that relate to smart contract interactions are organized under the `con
 
 A Soroban contract has its interface schema types embedded in the binary that gets deployed on-chain, making it possible to dynamically generate a custom CLI for each. The invoke subcommand makes use of this:
 
-    stellar contract invoke --id CCR6QKTWZQYW6YUJ7UP7XXZRLWQPFRV6SWBLQS4ZQOSAF4BOUD77OTE2 --source alice --network testnet -- \
-                            --help
+    stellar contract invoke --id CCR6QKTWZQYW6YUJ7UP7XXZRLWQPFRV6SWBLQS4ZQOSAF4BOUD77OTE2 --source alice --network testnet -- --help
 
 Anything after the `--` double dash (the \"slop\") is parsed as arguments to the contract-specific CLI, generated on-the-fly from the embedded schema. For the hello world example, with a function called `hello` that takes one string argument `to`, here's how you invoke it:
 
-    stellar contract invoke --id CCR6QKTWZQYW6YUJ7UP7XXZRLWQPFRV6SWBLQS4ZQOSAF4BOUD77OTE2 --source alice --network testnet -- \
-                            hello --to world
+    stellar contract invoke --id CCR6QKTWZQYW6YUJ7UP7XXZRLWQPFRV6SWBLQS4ZQOSAF4BOUD77OTE2 --source alice --network testnet -- hello --to world
 ";
 
 #[derive(Parser, Debug)]

cmd/soroban-cli/src/commands/network/container.rs

@@ -16,10 +16,11 @@ pub enum Cmd {
     ///
     /// Start a container running a Stellar node, RPC, API, and friendbot (faucet).
     ///
-    /// stellar network start <NETWORK> [OPTIONS]
+    /// `stellar network start NETWORK [OPTIONS]`
     ///
     /// By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command:
-    /// docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc
+    ///
+    /// `docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc`
     Start(start::Cmd),
     /// Stop a network started with `network container start`. For example, if you ran `network container start local`, you can use `network container stop local` to stop it.
     Stop(stop::Cmd),

cmd/soroban-cli/src/commands/network/container/start.rs

@@ -35,7 +35,7 @@ pub struct Cmd {
     #[arg(short = 'l', long)]
     pub limits: Option<String>,
 
-    /// Argument to specify the HOST_PORT:CONTAINER_PORT mapping
+    /// Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping
     #[arg(short = 'p', long, num_args = 1.., default_value = DEFAULT_PORT_MAPPING)]
     pub ports_mapping: Vec<String>,
 

cmd/soroban-cli/src/commands/network/mod.rs

@@ -34,10 +34,11 @@ pub enum Cmd {
     ///
     /// Start a container running a Stellar node, RPC, API, and friendbot (faucet).
     ///
-    /// stellar network start <NETWORK> [OPTIONS]
+    /// `stellar network start NETWORK [OPTIONS]`
     ///
     /// By default, when starting a testnet container, without any optional arguments, it will run the equivalent of the following docker command:
-    /// docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc
+    ///
+    /// `docker run --rm -p 8000:8000 --name stellar stellar/quickstart:testing --testnet --enable-soroban-rpc`
     Start(container::StartCmd),
     /// ⚠️ Deprecated: use `stellar container stop` instead
     ///