From 13d0ee665342ce94076c5187fdc2d8c99b4ac380 Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Wed, 10 Jul 2024 09:27:09 -0300 Subject: [PATCH 1/3] Improve markdown output so we can import it on stellar docs. (#1435) --- FULL_HELP_DOCS.md | 122 +++++------------- cmd/soroban-cli/Cargo.toml | 2 +- cmd/soroban-cli/src/bin/doc-gen.rs | 11 +- cmd/soroban-cli/src/commands/completion.rs | 10 +- cmd/soroban-cli/src/commands/events.rs | 10 +- cmd/soroban-cli/src/commands/mod.rs | 21 ++- .../src/commands/network/container.rs | 5 +- .../src/commands/network/container/start.rs | 2 +- cmd/soroban-cli/src/commands/network/mod.rs | 5 +- 9 files changed, 66 insertions(+), 122 deletions(-) diff --git a/FULL_HELP_DOCS.md b/FULL_HELP_DOCS.md index d61a26a17..2607b5f11 100644 --- a/FULL_HELP_DOCS.md +++ b/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 ` @@ -703,15 +647,11 @@ Watch the network for contract events * `--id ` — 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 ` — 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 ` — 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 ` — 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 [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] ` @@ -1133,7 +1075,7 @@ By default, when starting a testnet container, without any optional arguments, i * `-d`, `--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 ` — Optional argument to specify the limits for the local network only -* `-p`, `--ports-mapping ` — Argument to specify the HOST_PORT:CONTAINER_PORT mapping +* `-p`, `--ports-mapping ` — Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping Default value: `8000:8000` * `-t`, `--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 [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] ` @@ -1218,7 +1162,7 @@ By default, when starting a testnet container, without any optional arguments, i * `-d`, `--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 ` — Optional argument to specify the limits for the local network only -* `-p`, `--ports-mapping ` — Argument to specify the HOST_PORT:CONTAINER_PORT mapping +* `-p`, `--ports-mapping ` — Argument to specify the `HOST_PORT:CONTAINER_PORT` mapping Default value: `8000:8000` * `-t`, `--image-tag-override ` — Optional argument to override the default docker image tag for the given network @@ -1352,9 +1296,3 @@ Read cached action -
- - - This document was generated automatically by - clap-markdown. - diff --git a/cmd/soroban-cli/Cargo.toml b/cmd/soroban-cli/Cargo.toml index b4d341ad0..7d4a6ae81 100644 --- a/cmd/soroban-cli/Cargo.toml +++ b/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" diff --git a/cmd/soroban-cli/src/bin/doc-gen.rs b/cmd/soroban-cli/src/bin/doc-gen.rs index 96c6b09fd..4add9877c 100644 --- a/cmd/soroban-cli/src/bin/doc-gen.rs +++ b/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::(), - )?; + let content = clap_markdown::help_markdown_custom::(&options); + + std::fs::write(out_dir.join("FULL_HELP_DOCS.md"), content)?; Ok(()) } diff --git a/cmd/soroban-cli/src/commands/completion.rs b/cmd/soroban-cli/src/commands/completion.rs index 8bd1922d2..576352e04 100644 --- a/cmd/soroban-cli/src/commands/completion.rs +++ b/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)] diff --git a/cmd/soroban-cli/src/commands/events.rs b/cmd/soroban-cli/src/commands/events.rs index a16be5734..2f7e0b04e 100644 --- a/cmd/soroban-cli/src/commands/events.rs +++ b/cmd/soroban-cli/src/commands/events.rs @@ -44,15 +44,11 @@ pub struct Cmd { contract_ids: Vec, /// 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). diff --git a/cmd/soroban-cli/src/commands/mod.rs b/cmd/soroban-cli/src/commands/mod.rs index ac64d9f34..f6a4c28cf 100644 --- a/cmd/soroban-cli/src/commands/mod.rs +++ b/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)] diff --git a/cmd/soroban-cli/src/commands/network/container.rs b/cmd/soroban-cli/src/commands/network/container.rs index b4b3141d3..16e5d73be 100644 --- a/cmd/soroban-cli/src/commands/network/container.rs +++ b/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 [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), diff --git a/cmd/soroban-cli/src/commands/network/container/start.rs b/cmd/soroban-cli/src/commands/network/container/start.rs index b7f8d87a2..cc9619f1d 100644 --- a/cmd/soroban-cli/src/commands/network/container/start.rs +++ b/cmd/soroban-cli/src/commands/network/container/start.rs @@ -35,7 +35,7 @@ pub struct Cmd { #[arg(short = 'l', long)] pub limits: Option, - /// 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, diff --git a/cmd/soroban-cli/src/commands/network/mod.rs b/cmd/soroban-cli/src/commands/network/mod.rs index 75af88970..214f0573c 100644 --- a/cmd/soroban-cli/src/commands/network/mod.rs +++ b/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 [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 /// From 292d34acda2cf46ba1d2e58988431b2aa57dd8c0 Mon Sep 17 00:00:00 2001 From: Leigh McCulloch <351529+leighmcculloch@users.noreply.github.com> Date: Wed, 10 Jul 2024 23:01:37 +1000 Subject: [PATCH 2/3] Remove unnecessary brackets from readme (#1441) --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index 9f0a365e5..09f1561dc 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,6 @@ # Stellar CLI (stellar-cli) -[![Apache 2.0 licensed](https://img.shields.io/badge/license-apache%202.0-blue.svg)] +![Apache 2.0 licensed](https://img.shields.io/badge/license-apache%202.0-blue.svg) This repo is home to the Stellar CLI, the command-line multi-tool for running and deploying Stellar contracts on the Stellar network. From 0c4c1f033cffbdc53d187f5decb188a1f9223bba Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Wed, 10 Jul 2024 10:21:38 -0300 Subject: [PATCH 3/3] Use a shorter title. (#1443) --- FULL_HELP_DOCS.md | 2 +- cmd/soroban-cli/src/bin/doc-gen.rs | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/FULL_HELP_DOCS.md b/FULL_HELP_DOCS.md index 2607b5f11..4b3602a5a 100644 --- a/FULL_HELP_DOCS.md +++ b/FULL_HELP_DOCS.md @@ -1,4 +1,4 @@ -# Command-Line Help for the Stellar CLI +# Stellar CLI Manual This document contains the help content for the `stellar` command-line program. diff --git a/cmd/soroban-cli/src/bin/doc-gen.rs b/cmd/soroban-cli/src/bin/doc-gen.rs index 4add9877c..d3aa3ecb2 100644 --- a/cmd/soroban-cli/src/bin/doc-gen.rs +++ b/cmd/soroban-cli/src/bin/doc-gen.rs @@ -15,7 +15,7 @@ fn doc_gen() -> std::io::Result<()> { let options = clap_markdown::MarkdownOptions::new() .show_footer(false) .show_table_of_contents(false) - .title("Command-Line Help for the Stellar CLI".to_string()); + .title("Stellar CLI Manual".to_string()); let content = clap_markdown::help_markdown_custom::(&options);