From 4a3d6b643d340f1691c5f62050a768b635a9bffd Mon Sep 17 00:00:00 2001 From: Nando Vieira Date: Wed, 10 Jul 2024 11:05:08 -0300 Subject: [PATCH] Automatically generate stellar-cli help page. (#755) --- Dockerfile | 1 + docs/build/guides/cli/README.mdx | 2 +- .../example-contracts/liquidity-pool.mdx | 2 +- .../example-contracts/tokens.mdx | 2 +- .../smart-contracts/getting-started/setup.mdx | 83 +------------------ docs/data/README.mdx | 4 +- .../types/fully-typed-contracts.mdx | 2 +- .../migrate/evm/smart-contract-deployment.mdx | 2 +- .../migrate/evm/solidity-and-rust-basics.mdx | 2 +- docs/tokens/stellar-asset-contract.mdx | 2 +- docs/tools/README.mdx | 2 +- .../README.mdx} | 4 +- docs/tools/developer-tools/stellar-cli.mdx | 3 + package.json | 3 +- scripts/stellar_cli.mjs | 25 ++++++ 15 files changed, 46 insertions(+), 93 deletions(-) rename docs/tools/{developer-tools.mdx => developer-tools/README.mdx} (95%) create mode 100644 docs/tools/developer-tools/stellar-cli.mdx create mode 100644 scripts/stellar_cli.mjs diff --git a/Dockerfile b/Dockerfile index f46a448ee..bc5d55123 100644 --- a/Dockerfile +++ b/Dockerfile @@ -18,6 +18,7 @@ COPY . /app/ RUN yarn install RUN yarn rpcspec:build +RUN yarn stellar-cli:build RUN yarn build FROM nginx:1.17 diff --git a/docs/build/guides/cli/README.mdx b/docs/build/guides/cli/README.mdx index 46873061f..b804256e5 100644 --- a/docs/build/guides/cli/README.mdx +++ b/docs/build/guides/cli/README.mdx @@ -7,4 +7,4 @@ sidebar_position: 90 The [Stellar CLI] is a crucial tool for developers to use while creating and interacting with Stellar smart contracts. -[stellar cli]: ../../../tools/developer-tools.mdx#cli +[stellar cli]: ../../../tools/developer-tools/README.mdx#cli diff --git a/docs/build/smart-contracts/example-contracts/liquidity-pool.mdx b/docs/build/smart-contracts/example-contracts/liquidity-pool.mdx index b4921698c..b970e1b52 100644 --- a/docs/build/smart-contracts/example-contracts/liquidity-pool.mdx +++ b/docs/build/smart-contracts/example-contracts/liquidity-pool.mdx @@ -923,4 +923,4 @@ stellar contract invoke ` -[`stellar-cli`]: ../../../tools/developer-tools.mdx#cli +[`stellar-cli`]: ../../../tools/developer-tools/README.mdx#cli diff --git a/docs/build/smart-contracts/example-contracts/tokens.mdx b/docs/build/smart-contracts/example-contracts/tokens.mdx index aa8d9705c..f4d62cb5d 100644 --- a/docs/build/smart-contracts/example-contracts/tokens.mdx +++ b/docs/build/smart-contracts/example-contracts/tokens.mdx @@ -1021,4 +1021,4 @@ stellar contract invoke ` -[`stellar-cli`]: ../../../tools/developer-tools.mdx#cli +[`stellar-cli`]: ../../../tools/developer-tools/README.mdx#cli diff --git a/docs/build/smart-contracts/getting-started/setup.mdx b/docs/build/smart-contracts/getting-started/setup.mdx index cb9f9f1e1..7c6783e35 100644 --- a/docs/build/smart-contracts/getting-started/setup.mdx +++ b/docs/build/smart-contracts/getting-started/setup.mdx @@ -110,86 +110,11 @@ Report issues and share feedback about the Stellar CLI [here](https://github.com ::: -### Usage +### Documentation -Run the `stellar --help` command and you should see output like below. +The auto-generated comprehensive reference documentation is available [here](../../../tools/developer-tools/stellar-cli.mdx). -```console -$ stellar --help -Build, deploy, & interact with contracts; set identities to sign with; configure networks; generate keys; and more. - -Stellar Docs: https://developers.stellar.org -CLI Full Help Docs: https://github.com/stellar/stellar-cli/tree/main/FULL_HELP_DOCS.md - -The easiest way to get started is to generate a new identity: - - stellar keys generate alice - -You can use identities with the `--source` flag in other commands later. - -Commands that relate to smart contract interactions are organized under the `contract` subcommand. List them: - - stellar contract --help - -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 - -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 - - -Usage: stellar [OPTIONS] - -Commands: - completion Print shell completion code for the specified shell - contract Tools for smart contract developers - events Watch the network for contract events - keys Create and manage identities including keys and addresses - xdr Decode and encode XDR - network Start and configure networks - version Print version information - cache Cache for tranasctions and contract specs - -Options: - --global - Use global config - - -f, --filter-logs - Filter logs output. To turn on "stellar_cli::log::footprint=debug" or off "=off". Can also use env var `RUST_LOG` - - -q, --quiet - Do not write logs to stderr including `INFO` - - -v, --verbose - Log DEBUG events - - --very-verbose - Log DEBUG and TRACE events - - [aliases: vv] - - --list - List installed plugins. E.g. `stellar-hello` - - --no-cache - Do not cache your simulations and transactions - - [env: STELLAR_NO_CACHE=] - - -h, --help - Print help (see a summary with '-h') - - -V, --version - Print version - -TESTING_OPTIONS: - --config-dir - Location of config directory, default is "." -``` - -:::tip +### Autocompletion You can use `stellar completion` to generate shell completion for `bash`, `elvish`, `fish`, `powershell`, and `zsh`. You should absolutely try it out. It will feel like a super power! @@ -207,8 +132,6 @@ echo "source <(stellar completion --shell bash)" >> ~/.bashrc Users of non-bash shells may need to adapt the above commands to suit their needs. -::: - ### Configuring the CLI for Testnet Stellar has a test network called Testnet that you can use to deploy and test your smart contracts. It's a live network, but it's not the same as the Stellar public network. It's a separate network that is used for development and testing, so you can't use it for production apps. But it's a great place to test your contracts before you deploy them to the public network. diff --git a/docs/data/README.mdx b/docs/data/README.mdx index 8f9821c84..c844221b2 100644 --- a/docs/data/README.mdx +++ b/docs/data/README.mdx @@ -18,13 +18,13 @@ If the RPC does not otherwise serve your needs, please tell us why in the [Stell You have the option of [setting up your own RPC instance](./rpc/admin-guide.mdx) or using a publicly available service from [an infrastructure provider](./rpc/rpc-providers.mdx). -## [Data Indexers](../tools/developer-tools.mdx#data-indexers) +## [Data Indexers](../tools/developer-tools/README.mdx#data-indexers) Data indexers are specialized tools that process and index blockchain data, making it more accessible and queryable to end users. They transform raw blockchain data into a more structured format that’s easier for end users to interact with. Data indexers have advanced querying capabilities and enhanced analytics. They provide features such as statistical analysis of blockchain activity, visualization of transaction flows, or tracking DeFi metrics — capabilities that go beyond basic transaction lookup for current or historical state data. -Data indexers are a potentially more user-friendly, cost-effective choice for users. Check out several available data indexers for the Stellar network in our [Tools section](../tools/developer-tools.mdx#data-indexers). +Data indexers are a potentially more user-friendly, cost-effective choice for users. Check out several available data indexers for the Stellar network in our [Tools section](../tools/developer-tools/README.mdx#data-indexers). ## [Hubble](./hubble/README.mdx) diff --git a/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx b/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx index 0f0675e9b..77adb1e88 100644 --- a/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx +++ b/docs/learn/encyclopedia/contract-development/types/fully-typed-contracts.mdx @@ -25,7 +25,7 @@ When you compile a contract created with [soroban-sdk](../../../../tools/sdks/li Today, these interface types are formatted using [XDR](../../data-format/xdr.mdx), but this [may change](https://github.com/stellar/rs-soroban-sdk/issues/683) down the road. -The important part is that tooling can fetch these interface types to make your life easier. [Stellar CLI](../../../../tools/developer-tools.mdx#cli) is the first tool to do so. Specifically, one subcommand: +The important part is that tooling can fetch these interface types to make your life easier. [Stellar CLI](../../../../tools/developer-tools/README.mdx#cli) is the first tool to do so. Specifically, one subcommand: ## `stellar contract invoke` diff --git a/docs/learn/migrate/evm/smart-contract-deployment.mdx b/docs/learn/migrate/evm/smart-contract-deployment.mdx index c487317b8..94b028d27 100644 --- a/docs/learn/migrate/evm/smart-contract-deployment.mdx +++ b/docs/learn/migrate/evm/smart-contract-deployment.mdx @@ -26,7 +26,7 @@ Soroban and Hardhat are both frameworks that enable developers to build, test, a ### Soroban Framework -Soroban is a Rust-based framework tailored for developing smart contracts on the Stellar network. Designed as a lightweight framework, with [tools to support developers](../../../tools/developer-tools.mdx), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. +Soroban is a Rust-based framework tailored for developing smart contracts on the Stellar network. Designed as a lightweight framework, with [tools to support developers](../../../tools/developer-tools/README.mdx), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. ### Hardhat diff --git a/docs/learn/migrate/evm/solidity-and-rust-basics.mdx b/docs/learn/migrate/evm/solidity-and-rust-basics.mdx index f21803b06..0d30229b8 100644 --- a/docs/learn/migrate/evm/solidity-and-rust-basics.mdx +++ b/docs/learn/migrate/evm/solidity-and-rust-basics.mdx @@ -541,7 +541,7 @@ env.storage().instance().get(&COUNTER).unwrap_or(0) This is a repeat of the code we saw earlier, which retrieves the value associated with the key `COUNTER` from the contract storage. If there is no value set for the key `COUNTER`, a default value of 0 is used. Finally, the `unwrap()` method is called to extract the actual value from the `Ok` wrapper, which is then returned to the caller of the function. -Now that we have written our smart contract, it's time to explore how we can interact with it using the [Stellar CLI](../../../tools/developer-tools.mdx#cli), one of many robust [Developer Tools](../../../tools/developer-tools.mdx) available. This powerful command-line tool allows us to interact with the Soroban Virtual Machine from a local machine, providing us with an efficient and flexible way to manage our smart contract. +Now that we have written our smart contract, it's time to explore how we can interact with it using the [Stellar CLI](../../../tools/developer-tools/README.mdx#cli), one of many robust [Developer Tools](../../../tools/developer-tools/README.mdx) available. This powerful command-line tool allows us to interact with the Soroban Virtual Machine from a local machine, providing us with an efficient and flexible way to manage our smart contract. ### Interacting with the Rust Smart Counter diff --git a/docs/tokens/stellar-asset-contract.mdx b/docs/tokens/stellar-asset-contract.mdx index 2429cf2f6..c43a8686e 100644 --- a/docs/tokens/stellar-asset-contract.mdx +++ b/docs/tokens/stellar-asset-contract.mdx @@ -57,7 +57,7 @@ Or the [Stellar SDK] can be used as shown [here](../learn/encyclopedia/contract- Anyone can deploy the instances of Stellar Asset Contract. Note, that the initialization of the Stellar Asset Contracts happens automatically during the deployment. Asset Issuer will have the administrative permissions after the contract has been deployed. [contract_id]: https://github.com/stellar/stellar-xdr/blob/dc23adf60e095a6ce626b2b09128e58a5eae0cd0/Stellar-transaction.x#L661 -[stellar-cli]: ../tools/developer-tools.mdx#cli +[stellar-cli]: ../tools/developer-tools/README.mdx#cli ## Interacting with classic Stellar assets diff --git a/docs/tools/README.mdx b/docs/tools/README.mdx index fb8c01147..11a228bc5 100644 --- a/docs/tools/README.mdx +++ b/docs/tools/README.mdx @@ -9,7 +9,7 @@ This section of the docs will provide links to the SDKs and developer tools for Stellar’s Software Development Kits (SDKs) provide devs with the tools, libraries, and documentation to interact with and develop on the blockchain. They simplify tasks such as creating and deploying smart contracts and sending transactions while also offering APIs to access data and integrate functionalities into applications. -## [Developer Tools](./developer-tools.mdx) +## [Developer Tools](./developer-tools/README.mdx) Find SDF and ecosystem-maintained developer tools that help streamline the development process for applications and smart contracts on Stellar. diff --git a/docs/tools/developer-tools.mdx b/docs/tools/developer-tools/README.mdx similarity index 95% rename from docs/tools/developer-tools.mdx rename to docs/tools/developer-tools/README.mdx index 32b1c7232..7ff8b8743 100644 --- a/docs/tools/developer-tools.mdx +++ b/docs/tools/developer-tools/README.mdx @@ -57,9 +57,9 @@ Ortege is an AI-powered blockchain analytics & insights tool for Stellar, making The command line interface to Soroban smart contracts. It allows you to build, deploy, and interact with smart contracts; configure identities; generate key pairs; manage networks; and more. -Install Stellar CLI as explained in [Setup](../build/smart-contracts/getting-started/setup.mdx#install-the-stellar-cli). For examples on how to use the Stellar CLI, please see [Stellar CLI Guide](../build/guides/cli/README.mdx). +Install Stellar CLI as explained in [Setup](../../build/smart-contracts/getting-started/setup.mdx#install-the-stellar-cli). For examples on how to use the Stellar CLI, please see [Stellar CLI Guide](../../build/guides/cli/README.mdx). -The auto-generated comprehensive reference documentation is available [here](https://github.com/stellar/stellar-cli/blob/main/FULL_HELP_DOCS.md). +The auto-generated comprehensive reference documentation is available [here](./stellar-cli.mdx). ## Data Indexers diff --git a/docs/tools/developer-tools/stellar-cli.mdx b/docs/tools/developer-tools/stellar-cli.mdx new file mode 100644 index 000000000..171b965ce --- /dev/null +++ b/docs/tools/developer-tools/stellar-cli.mdx @@ -0,0 +1,3 @@ +# Stellar CLI Manual + +Stub file: the real file is generated in build time by `yarn stellar-cli:build`. diff --git a/package.json b/package.json index 39cc2e0c4..e10868092 100644 --- a/package.json +++ b/package.json @@ -26,7 +26,8 @@ "prepare": "husky install", "postinstall": "patch-package", "rpcspec:build": "node openrpc/scripts/build.mjs", - "rpcspec:validate": "node openrpc/scripts/build.mjs && node openrpc/scripts/validate.mjs" + "rpcspec:validate": "node openrpc/scripts/build.mjs && node openrpc/scripts/validate.mjs", + "stellar-cli:build": "node scripts/stellar_cli.mjs" }, "dependencies": { "@docusaurus/core": "^2.2.0", diff --git a/scripts/stellar_cli.mjs b/scripts/stellar_cli.mjs new file mode 100644 index 000000000..16114afe2 --- /dev/null +++ b/scripts/stellar_cli.mjs @@ -0,0 +1,25 @@ +import fs from "fs"; + +const headers = { "user-agent": "https://github.com/stellar/stellar-docs" }; +let result = await fetch("https://crates.io/api/v1/crates/stellar-cli", { + headers, +}); +const json = await result.json(); +const version = json.crate.newest_version; + +result = await fetch( + // `https://github.com/stellar/stellar-cli/raw/v${version}/FULL_HELP_DOCS.md`, + `https://github.com/stellar/stellar-cli/raw/main/FULL_HELP_DOCS.md`, + { headers }, +); +let text = await result.text(); + +text = `--- +sidebar_position: 20 +description: This document contains the help content for the stellar command-line program. +--- + +${text} +`; + +fs.writeFileSync("docs/tools/developer-tools/stellar-cli.mdx", text);