From c2fd200448f8ae24757c809ff036ef0e85fa76ae Mon Sep 17 00:00:00 2001 From: Elliot Voris Date: Fri, 23 Feb 2024 13:02:18 -0600 Subject: [PATCH] [Stellar Merge] Tools Section (#739) * create redirects for tools and SDKs pages * adjust some redirect URLs to better reflect new stellar-docs pages * forgot a semicolon! * linking to migrated developer tools page * fine-tuning some redirects * add a list of "already migrated" stuff to the sidebar * remove SDKs content that's being migrated * fix the resulting broken links * Revert "remove SDKs content that's being migrated" This reverts commit 6dd2a28a8f124e876607a9bf30894a420ea6eb08. * Revert "linking to migrated developer tools page" This reverts commit fc2340818a08c42fc1f13f6a49d97111610c9100. * try this method of turning docs into external links * include soroban-cli page in the tools migration * change cli links to developer docs * use by-name params in pagination example (#743) Refs: #728 --- docs/developer-tools.mdx | 4 ++++ docs/guides/cli/README.mdx | 2 +- .../migrate/evm/smart-contract-deployment.mdx | 8 ++++---- docs/migrate/evm/solidity-and-rust-basics.mdx | 4 ++-- docs/reference/sdks/build-your-own-sdk.mdx | 4 ++++ .../sdks/interact-with-contracts.mdx | 4 ++++ docs/reference/sdks/write-contracts.mdx | 4 ++++ docs/reference/soroban-cli.mdx | 10 ++++++++++ .../stellar-transaction.mdx | 2 +- .../types/built-in-types.mdx | 2 +- .../types/fully-typed-contracts.mdx | 4 ++-- docs/tokens/stellar-asset-contract.mdx | 2 +- docs/tokens/token-interface.mdx | 4 ++-- docs/tutorials/liquidity-pool.mdx | 2 +- docs/tutorials/tokens.mdx | 2 +- nginx/includes/redirects.conf | 15 +++++++++----- src/sidebar-generator.js | 20 ++++++++++++++++++- 17 files changed, 71 insertions(+), 22 deletions(-) diff --git a/docs/developer-tools.mdx b/docs/developer-tools.mdx index 1c0caeae..170934f6 100644 --- a/docs/developer-tools.mdx +++ b/docs/developer-tools.mdx @@ -1,6 +1,10 @@ --- sidebar_position: 75 title: Developer Tools +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/developer-tools + label: Developer Tools --- :::info diff --git a/docs/guides/cli/README.mdx b/docs/guides/cli/README.mdx index e87ce3df..d85e7aa7 100644 --- a/docs/guides/cli/README.mdx +++ b/docs/guides/cli/README.mdx @@ -5,4 +5,4 @@ hide_table_of_contents: true The [Soroban CLI] is a crucial tool for developers to use while creating and interacting with Soroban smart contracts. -[Soroban CLI]: ../../reference/soroban-cli.mdx +[Soroban CLI]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli diff --git a/docs/migrate/evm/smart-contract-deployment.mdx b/docs/migrate/evm/smart-contract-deployment.mdx index a09ce525..e4ad03d5 100644 --- a/docs/migrate/evm/smart-contract-deployment.mdx +++ b/docs/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](../../reference/soroban-cli), 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](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli), Soroban allows developers to develop smart contracts through a simple and intuitive workflow. ### Hardhat @@ -44,7 +44,7 @@ Soroban, with its lightweight design, offers developers an exceptional platform Hardhat offers a streamlined workflow for deploying smart contracts on the Ethereum Virtual Machine, with key components such as `ethers.js`, `scripts`, and `testing` playing crucial roles. -On the other hand, Soroban presents a compelling alternative, boasting powerful SDKs that facilitate smart contract development and deployment. In the upcoming section, we will delve into [Soroban's SDKs](../../category/sdks), drawing comparisons with Hardhat components, and highlighting the unique advantages each platform brings to the table. +On the other hand, Soroban presents a compelling alternative, boasting powerful SDKs that facilitate smart contract development and deployment. In the upcoming section, we will delve into [Soroban's SDKs](https://developers.stellar.org/docs/tools/sdks), drawing comparisons with Hardhat components, and highlighting the unique advantages each platform brings to the table. ### Ethers.js @@ -62,7 +62,7 @@ async function main() { ### Soroban Client -Soroban offers a comparable library, [`stellar-sdk`](../../reference/sdks/interact-with-contracts.mdx#javascript-sdk), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for Soroban RPC methods as well as the traditional Horizon API, simplifying the process of building and signing transactions. Additionally, `stellar-sdk` streamlines communication with RPC instances and supports submitting transactions or querying network state with ease. +Soroban offers a comparable library, [`stellar-sdk`](https://developers.stellar.org/docs/tools/sdks/library#javascript-sdk), that enables seamless interaction smart contracts deployed on the Stellar Network. This library supplies a comprehensive networking layer API for Soroban RPC methods as well as the traditional Horizon API, simplifying the process of building and signing transactions. Additionally, `stellar-sdk` streamlines communication with RPC instances and supports submitting transactions or querying network state with ease. ### Scripts @@ -89,7 +89,7 @@ main() ### Soroban Scripts -Soroban offers an extensive collection of SDKs that include scripting capabilities, ensuring a smooth workflow for deploying and managing smart contracts. Developers can automate tasks such as compiling, deploying, and interacting with smart contracts using a variety of SDKs that support scripting in languages like [`JavaScript`, `TypeScript`, `Python`, and others](../../category/sdks). +Soroban offers an extensive collection of SDKs that include scripting capabilities, ensuring a smooth workflow for deploying and managing smart contracts. Developers can automate tasks such as compiling, deploying, and interacting with smart contracts using a variety of SDKs that support scripting in languages like [`JavaScript`, `TypeScript`, `Python`, and others](https://developers.stellar.org/docs/tools/sdks). ```python # This example shows how to deploy a compiled contract to the Stellar network. diff --git a/docs/migrate/evm/solidity-and-rust-basics.mdx b/docs/migrate/evm/solidity-and-rust-basics.mdx index cdcd8f08..224e3067 100644 --- a/docs/migrate/evm/solidity-and-rust-basics.mdx +++ b/docs/migrate/evm/solidity-and-rust-basics.mdx @@ -455,7 +455,7 @@ impl IncrementContract { } ``` -This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](../../reference/sdks/write-contracts.mdx#soroban-rust-sdk), a Rust-based smart contract development toolkit developed by the [Stellar Development Foundation (SDF)](https://stellar.org/foundation). The Soroban Rust SDK provides a powerful set of tools for writing smart contracts that run on the Soroban Virtual Machine. +This code is an implementation of a smart contract written in Rust using the [`Soroban Rust SDK`](https://developers.stellar.org/docs/tools/sdks/library#soroban-rust-sdk), a Rust-based smart contract development toolkit developed by the [Stellar Development Foundation (SDF)](https://stellar.org/foundation). The Soroban Rust SDK provides a powerful set of tools for writing smart contracts that run on the Soroban Virtual Machine. Here's a line-by-line explanation of what the code is doing: @@ -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 [Soroban-CLI](../../reference/soroban-cli.mdx), one of many robust [Developer 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 [Soroban-CLI](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli), one of many robust [Developer Tools](https://developers.stellar.org/docs/tools/developer-tools) 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/reference/sdks/build-your-own-sdk.mdx b/docs/reference/sdks/build-your-own-sdk.mdx index 5ddf696a..70e1db7e 100644 --- a/docs/reference/sdks/build-your-own-sdk.mdx +++ b/docs/reference/sdks/build-your-own-sdk.mdx @@ -2,6 +2,10 @@ sidebar_position: 30 title: Build Your Own SDK description: A guide to developing Soroban SDKs for languages other than Rust. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/sdks/build-your-own + label: Build Your Own SDK --- Soroban currently has one SDK for writing contracts in Rust, which can be found [here][soroban-sdk]. diff --git a/docs/reference/sdks/interact-with-contracts.mdx b/docs/reference/sdks/interact-with-contracts.mdx index 27e4cc19..8e74f1ab 100644 --- a/docs/reference/sdks/interact-with-contracts.mdx +++ b/docs/reference/sdks/interact-with-contracts.mdx @@ -2,6 +2,10 @@ sidebar_position: 20 title: Interact with Contracts description: SDKs support writing Soroban applications in many languages. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/sdks/library + label: Interact with Contracts --- ## JavaScript SDK diff --git a/docs/reference/sdks/write-contracts.mdx b/docs/reference/sdks/write-contracts.mdx index 5f902a3f..1ac4299a 100644 --- a/docs/reference/sdks/write-contracts.mdx +++ b/docs/reference/sdks/write-contracts.mdx @@ -2,6 +2,10 @@ sidebar_position: 10 title: Write Contracts description: SDKs support writing Soroban contracts in Rust and AssemblyScript. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/sdks/library + label: Write Contracts --- ## Soroban Rust SDK diff --git a/docs/reference/soroban-cli.mdx b/docs/reference/soroban-cli.mdx index bd3dafc1..9f6b9b50 100644 --- a/docs/reference/soroban-cli.mdx +++ b/docs/reference/soroban-cli.mdx @@ -2,8 +2,18 @@ sidebar_position: 80 title: Soroban CLI description: The tool for interacting with deployed contracts. +sidebar_custom_props: + migration: + href: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli + label: Soroban CLI --- +:::danger These are not the droids you're looking for + +This page has been migrated to the Stellar Developers documentation. Please [click here](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli) for the most up-to-date information + +::: + Soroban CLI is the command line interface to Soroban. It allows you to build, deploy, and interact with smart contracts; configure identities; generate key pairs; manage networks; and more. Install Soroban CLI as explained in [Setup](../getting-started/setup.mdx). diff --git a/docs/soroban-internals/contract-interactions/stellar-transaction.mdx b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx index 528de15e..284e5005 100644 --- a/docs/soroban-internals/contract-interactions/stellar-transaction.mdx +++ b/docs/soroban-internals/contract-interactions/stellar-transaction.mdx @@ -402,7 +402,7 @@ The `hostFunction` in `InvokeHostFunctionOp` will be executed by the Soroban hos ##### JavaScript Usage -Each of these variations of host function invocation has convenience methods in the [JavaScript SDK](../../reference/sdks/interact-with-contracts.mdx#javascript-sdk): +Each of these variations of host function invocation has convenience methods in the [JavaScript SDK](https://developers.stellar.org/docs/tools/sdks/library#javascript-sdk): - [`Operation.invokeHostFunction`](https://stellar.github.io/js-stellar-sdk/Operation.html#.invokeHostFunction) is the lowest-level method that corresponds directly to the XDR. - [`Operation.invokeContractFunction`](https://stellar.github.io/js-stellar-sdk/Operation.html#.invokeContractFunction) is an abstraction to invoke the method of a particular contract, similar to [`Contract.call`](https://stellar.github.io/js-stellar-sdk/Contract.html#call). diff --git a/docs/soroban-internals/types/built-in-types.mdx b/docs/soroban-internals/types/built-in-types.mdx index 05129c1f..446539ce 100644 --- a/docs/soroban-internals/types/built-in-types.mdx +++ b/docs/soroban-internals/types/built-in-types.mdx @@ -25,7 +25,7 @@ Built-in types are available to all contracts for use as contract function inputs and outputs, and are defined by the [environment] and the [Rust SDK]. [environment]: ../environment-concepts.mdx -[Rust SDK]: ../../reference/sdks/write-contracts.mdx#soroban-rust-sdk +[Rust SDK]: https://developers.stellar.org/docs/tools/sdks/library#soroban-rust-sdk :::tip diff --git a/docs/soroban-internals/types/fully-typed-contracts.mdx b/docs/soroban-internals/types/fully-typed-contracts.mdx index 741ffe7b..05a34608 100644 --- a/docs/soroban-internals/types/fully-typed-contracts.mdx +++ b/docs/soroban-internals/types/fully-typed-contracts.mdx @@ -25,11 +25,11 @@ sidebar_label: Fully-Typed Contracts /> -When you compile a contract created with [soroban-sdk](../../reference/sdks/write-contracts.mdx#soroban-rust-sdk), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. +When you compile a contract created with [soroban-sdk](https://developers.stellar.org/docs/tools/sdks/library#soroban-rust-sdk), the Wasm file ends up with a [custom section](https://webassembly.github.io/spec/core/appendix/custom.html) containing a machine-readable description of your contract's interface types, sometimes called its [spec](https://github.com/stellar/rs-soroban-sdk/tree/main/soroban-spec) or its [API](https://github.com/stellar/soroban-docs/pull/381#issuecomment-1507283476). This is similar to [ABIs](https://www.quicknode.com/guides/ethereum-development/smart-contracts/what-is-an-abi/) in Ethereum, except that Soroban will store every single one of them on-chain from day one, and they include the comments from the contract's author. Today, these interface types are formatted using [XDR](https://developers.stellar.org/docs/encyclopedia/xdr), 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. [Soroban CLI](../../reference/soroban-cli.mdx) 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. [Soroban CLI](https://developers.stellar.org/docs/tools/developer-tools#soroban-cli) is the first tool to do so. Specifically, one subcommand: ## `soroban contract invoke` diff --git a/docs/tokens/stellar-asset-contract.mdx b/docs/tokens/stellar-asset-contract.mdx index 7ac0e2ae..956e8759 100644 --- a/docs/tokens/stellar-asset-contract.mdx +++ b/docs/tokens/stellar-asset-contract.mdx @@ -52,7 +52,7 @@ 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 -[Soroban-CLI]: ../reference/soroban-cli.mdx +[Soroban-CLI]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli ## Interacting with classic Stellar assets diff --git a/docs/tokens/token-interface.mdx b/docs/tokens/token-interface.mdx index 92666861..7d6ed066 100644 --- a/docs/tokens/token-interface.mdx +++ b/docs/tokens/token-interface.mdx @@ -35,8 +35,8 @@ consistent with the interface described here: ### Code The interface below uses the Rust -[soroban-sdk](../reference/sdks/write-contracts.mdx#soroban-rust-sdk) to declare -a trait that complies with the +[soroban-sdk](https://developers.stellar.org/docs/tools/sdks/library#soroban-rust-sdk) +to declare a trait that complies with the [SEP-41](https://github.com/stellar/stellar-protocol/blob/master/ecosystem/sep-0041.md) token interface. diff --git a/docs/tutorials/liquidity-pool.mdx b/docs/tutorials/liquidity-pool.mdx index 25fd46d6..9cc7e1c4 100644 --- a/docs/tutorials/liquidity-pool.mdx +++ b/docs/tutorials/liquidity-pool.mdx @@ -1014,4 +1014,4 @@ soroban contract invoke \ --min_b 196 \ ``` -[`soroban-cli`]: ../reference/soroban-cli.mdx +[`soroban-cli`]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli diff --git a/docs/tutorials/tokens.mdx b/docs/tutorials/tokens.mdx index ec961950..38e004dc 100644 --- a/docs/tutorials/tokens.mdx +++ b/docs/tutorials/tokens.mdx @@ -1071,4 +1071,4 @@ soroban contract invoke \ --id GBZV3NONYSUDVTEHATQO4BCJVFXJO3XQU5K32X3XREVZKSMMOZFO4ZXR ``` -[`soroban-cli`]: ../reference/soroban-cli.mdx +[`soroban-cli`]: https://developers.stellar.org/docs/tools/developer-tools#soroban-cli diff --git a/nginx/includes/redirects.conf b/nginx/includes/redirects.conf index b8914662..01678fde 100644 --- a/nginx/includes/redirects.conf +++ b/nginx/includes/redirects.conf @@ -6,9 +6,7 @@ rewrite "^/docs/tutorials/deploy-to-futurenet$" "/docs/getting-started/deploy-to rewrite "^/fundamentals-and-concepts/faq$" "/docs/faq" permanent; rewrite "^/docs/examples/events$" "/docs/tutorials/events" permanent; rewrite "^/docs/learn/rust-dialect$" "/docs/soroban-internals/rust-dialect" permanent; -rewrite "^/docs/reference/command-line$" "/docs/reference/soroban-cli" permanent; rewrite "^/docs/advanced-tutorials/liquidity-pool-b6f$" "/docs/tutorials/liquidity-pool" permanent; -rewrite "^/reference/soroban-cli$" "/docs/reference/soroban-cli" permanent; rewrite "^/docs(/category)?/learn$" "/docs/category/soroban-internals" permanent; rewrite "^/docs/category/fundamentals-and-concepts$" "/docs/category/soroban-internals" permanent; rewrite "^/docs/built-in-contracts/token$" "/docs/tokens/stellar-asset-contract" permanent; @@ -17,7 +15,6 @@ rewrite "^/docs/getting-started/deploy-to-futurenet$" "/docs/getting-started/dep rewrite "^/api/incomplete-methods$" "/api/methods" permanent; rewrite "^/docs/tutorials/testing$" "/docs/soroban-internals/debugging" permanent; rewrite "^/docs/category/how-to-guides$" "/docs/guides" permanent; -rewrite "^/docs/SDKs/rust$" "/docs/reference/sdks/write-contracts" permanent; rewrite "^/docs/getting-started/connect-freighter-wallet$" "/docs/reference/freighter" permanent; rewrite "^/docs/common-interfaces/token$" "/docs/tokens/token-interface" permanent; rewrite "^/docs/how-to-guides/tokens$" "/docs/tutorials/tokens" permanent; @@ -34,8 +31,6 @@ rewrite "^/docs/fundamentals-and-concepts/migrating-from-evm(/.*)$" "/docs/migra rewrite "^/docs/reference/releases$" "/docs/releases" permanent; rewrite "^/docs/fundamentals-and-concepts/faq$" "/docs/faq" permanent; rewrite "^/docs/reference/testnet$" "/docs/reference/networks" permanent; -rewrite "^/docs/reference/sdks/(rust|assemblyscript-sdk)$" "/docs/reference/sdks/write-contracts" permanent; -rewrite "^/docs/reference/sdks/(js|python|ios-sdk|flutter-sdk|php-sdk|elixir|java)$" "/docs/reference/sdks/interact-with-contracts" permanent; rewrite "^/docs/fundamentals-and-concepts/(built-in-types|custom-types|fully-typed-contracts)$" "/docs/soroban-internals/types/$1" permanent; rewrite "^/docs/fundamentals-and-concepts/invoking-contracts-with-transactions$" "/docs/soroban-internals/contract-interactions/stellar-transaction" permanent; rewrite "^/docs/soroban-internals/contract-interactions/stellar-transactions$" "/docs/soroban-internals/contract-interactions/stellar-transaction" permanent; @@ -43,3 +38,13 @@ rewrite "^/docs/fundamentals-and-concepts/interacting-with-contracts$" "/docs/so rewrite "^/docs/(basic|advanced)-tutorials(/.*)$" "/docs/tutorials$2" permanent; rewrite "^/docs/fundamentals-and-concepts(/.*)$" "/docs/soroban-internals$1" permanent; rewrite "^/docs/notes" "/meetings" permanent; +# BEGIN merge redirects +rewrite "^/docs/developer-tools" "https://developers.stellar.org/docs/tools/developer-tools" permanent; +rewrite "^/docs/SDKs/rust$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; +rewrite "^/docs/reference/sdks/write-contracts" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/docs/reference/sdks/build-your-own-sdk" "https://developers.stellar.org/docs/tools/sdks/build-your-own" permanent; +rewrite "^/docs/reference/sdks.*$" "https://developers.stellar.org/docs/tools/sdks/library" permanent; +rewrite "^/docs/category/sdks$" "https://developers.stellar.org/docs/tools/sdks" permanent; +rewrite "^/reference/soroban-cli$" "https://developers.stellar.org/docs/tools/developer-tools#soroban-cli" permanent; +rewrite "^/docs/reference/command-line$" "https://developers.stellar.org/docs/tools/developer-tools#soroban-cli" permanent; +rewrite "^/docs/reference/soroban-cli$" "https://developers.stellar.org/docs/tools/developer-tools#soroban-cli" permanent; diff --git a/src/sidebar-generator.js b/src/sidebar-generator.js index 338353d5..0fe8a08d 100644 --- a/src/sidebar-generator.js +++ b/src/sidebar-generator.js @@ -1,6 +1,24 @@ const fs = require('fs') const path = require('path') +const migrationLinksRecursive = (sidebarItems) => { + const result = sidebarItems.map((sidebarItem) => { + if (sidebarItem.type === 'category') { + return {...sidebarItem, items: migrationLinksRecursive(sidebarItem.items)} + } + + if (sidebarItem.customProps?.migration?.href && sidebarItem.customProps?.migration?.label) { + sidebarItem = { + type: 'link', + href: sidebarItem.customProps.migration.href, + label: sidebarItem.customProps.migration.label, + } + } + return sidebarItem + }) + return result +} + module.exports = async ({ defaultSidebarItemsGenerator, ...args }) => { if (args.version.contentPath.endsWith('docs')) { @@ -31,5 +49,5 @@ module.exports = async ({ defaultSidebarItemsGenerator, ...args }) => { } const sidebarItems = await defaultSidebarItemsGenerator({ ...args }) - return sidebarItems + return migrationLinksRecursive(sidebarItems) }