diff --git a/docs/tools/developer-tools/jupyter-notebooks.mdx b/docs/tools/developer-tools/jupyter-notebooks.mdx new file mode 100644 index 000000000..c28e6716e --- /dev/null +++ b/docs/tools/developer-tools/jupyter-notebooks.mdx @@ -0,0 +1,79 @@ +--- +title: Jupyter Notebooks +description: Experiment with contracts in Jupyter Notebooks +sidebar_label: Jupyter Notebooks +sidebar_position: 71 +--- + +# Jupyter Notebooks + +Jupyter Notebooks are a document format that can include code, text, and other rich output. And with the appropriate setup they support Soroban Rust contracts. + +To use Soroban contracts in a Jupyter Notebook, the following setup is required. The following setup uses Visual Studio Code, but any Jupyter client and server can be used. + +:::caution + +Rust support in Jupyter Notebooks is experimental. You might run into bugs, or unexpected behavior. + +::: + +## Getting Started + +1. Install [Visual Studio Code] (VSCode) +2. Install the [Jupyter Notebook extension] in VSCode +3. Install the `evcxr` Rust Jupyter kernel with: + ``` + cargo install --locked evcxr_jupyter + evcxr_jupyter --install + ``` +4. Run the `Create: New Jupyter Notebook` command in VSCode +5. Click the `Detecting` button in the top right. +6. Select `Jupyter Kernel...` +7. Select `Rust` +8. Enter on the first line an import of the `soroban-sdk` dependency with the `testutils` feature enabled. + ```rust + :dep soroban-sdk = { version = "21.3.0", features = ["testutils"] } + ``` +9. Enter a contract. For example: + + ```rust + use soroban_sdk::{contract, contractimpl}; + + #[contract] + pub struct Contract; + + #[contractimpl] + impl Contract { + pub fn add(x: u32, y: u32) -> u32 { + x+y + } + } + ``` + +10. Enter some code to create a Soroban environment, register the contract, and invoke it. + +```rust +use soroban_sdk::{Env}; + +let env = Env::default(); +let id = env.register_contract(None, Contract); +let client: ContractClient = ContractClient::new(&env, &id); +client.add(&1, &2) +``` + +11. Click the play button to run the code. + +Congratulations you have a Jupyter Notebook with contract code that should look something like the screenshot below, ready for hacking and experimenting. + +## Screenshot + +![A running Jupyter notebook](jupyter-notebooks.png) + +## Community + +Have ideas for how to improve Soroban contracts in Jupyter Notebooks? Join the community on [Discord]. + +[Discord]: https://discord.com/channels/897514728459468821/1263811925813366794 +[Visual Studio Code]: https://code.visualstudio.com +[Jupyter Notebook extension]: https://marketplace.visualstudio.com/items?itemName=ms-toolsai.jupyter +[Jupyter Desktop]: https://github.com/jupyterlab/jupyterlab-desktop diff --git a/docs/tools/developer-tools/jupyter-notebooks.png b/docs/tools/developer-tools/jupyter-notebooks.png new file mode 100644 index 000000000..76e58ca4d Binary files /dev/null and b/docs/tools/developer-tools/jupyter-notebooks.png differ