chore(docs): moving tutorials and quick starts around, spinning off c…

…odespaces page (#6777)
AztecProtocol · Jun 25, 2024 · 1542fa6 · 1542fa6
1 parent 924c3f8
commit 1542fa6
Show file tree

Hide file tree

Showing 18 changed files with 144 additions and 145 deletions.
diff --git a/.devcontainer/scripts/onCreateCommand.sh b/.devcontainer/scripts/onCreateCommand.sh
@@ -11,11 +11,11 @@ if ! grep -q "PXE_URL" ~/.bashrc; then
 fi
 
 if ! grep -q "alias sandbox" ~/.bashrc; then
-    echo "alias sandbox=\"npx create-aztec-app sandbox\"" >> ~/.bashrc
+    echo "alias sandbox=\"npx aztec-app sandbox\"" >> ~/.bashrc
 fi
 
 source ~/.bashrc
-yes | npx create-aztec-app -t $TYPE -n $NAME -s
+yes | npx aztec-app -t $TYPE -n $NAME -s
 mv $NAME/* $NAME/.* .
 rm -rf $NAME
 

diff --git a/.devcontainer/scripts/postAttachCommand.sh b/.devcontainer/scripts/postAttachCommand.sh
@@ -5,7 +5,7 @@ NAME=$2
 apt install gh
 gh codespace ports visibility 8080:public -c $CODESPACE_NAME
 
-npx create-aztec-app sandbox start
+npx aztec-app sandbox start
 
 r=$(tput sgr0)       # Reset color
 bold=$(tput bold)    # Bold text

diff --git a/docs/.gitignore b/docs/.gitignore
@@ -24,3 +24,4 @@ yarn-error.log*
 
 docs/reference/aztecjs
 docs/reference/smart_contract_reference/aztec-nr
+test-results
diff --git a/docs/docs/aztec/_category_.json b/docs/docs/aztec/_category_.json
@@ -1,6 +1,6 @@
 {
     "label": "Aztec",
-    "position": 0,
+    "position": 1,
     "collapsible": true,
     "collapsed": true
 }
diff --git a/docs/docs/getting_started.md b/docs/docs/getting_started.md
@@ -2,43 +2,45 @@
 title: Quickstart
 ---
 
-The easiest way to start developing on Aztec is simply to click on one of these buttons:
+The easiest way to start developing on Aztec locally is through `npx aztec-app`. This is a convenient way of installing the development environment (A.K.A. Sandbox) and starting new projects from a boilerplate.
 
-[![One-Click React Starter](/img/codespaces_badges/react_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Freact%2Fdevcontainer.json) [![One-Click HTML/TS Starter](/img/codespaces_badges/vanilla_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Fvanilla%2Fdevcontainer.json) [![One-Click Token Starter](/img/codespaces_badges/token_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Ftoken%2Fdevcontainer.json)
+To locally install the Sandbox without other tools, see [here](./getting_started/manual_install.md).
 
-That's it!
+## Prerequisites
 
-This creates a codespace with a prebuilt image containing one of the "Aztec Boxes" and a development network (sandbox). 
-- You can develop directly on the codespace, push it to a repo, make yourself at home.
-- You can also just use the sandbox that comes with it. The URL will be logged, you just need to use it as your `PXE_URL`.
+- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm))
+- Docker (visit [this page of the Docker docs](https://docs.docker.com/get-docker/) on how to install it)
 
-## Develop Locally
+### Run the `npx` script
 
-The above method uses Aztec boxes to install the sandbox and clone the repo. You can use it too to get started on your own machine and use your own IDE.
+Thanks to Node, you can run the recommended `npx script`:
+
+```bash
+npx aztec-app
+```
 
-You can also [install the sandbox manually](/reference/sandbox_reference).
+This script gives you some options to bootstrap a new project, start/stop the sandbox, or see the logs. Run `npx aztec-app -h` for a list of options.
 
-### Prerequisites
+## Install Noir LSP (recommended)
 
-- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm))
-- Docker (visit [this page of the Docker docs](https://docs.docker.com/get-docker/) on how to install it)
+Install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) to get syntax highlighting, syntax error detection and go-to definitions for your Aztec contracts.
 
-### Run the `npx` script
+Once the extension is installed, check your nargo binary by hovering over `Nargo` in the status bar on the bottom right of the application window. Click to choose the path to `aztec-nargo` (or regular `nargo`, if you have that installed).
 
-With the node installation, you now should have `npm` and be able to run `npx` scripts. You can do that by running:
+You can print the path of your `aztec-nargo` executable by running:
 
 ```bash
-npx create-aztec-app
+which aztec-nargo
 ```
 
-And follow the instructions. If all goes well, you should now have a development environment running locally on your machine.
-
-You can run `npx create-aztec-app sandbox -h` to start, stop, update and output logs from the sandbox. 
+To specify a custom nargo executable, go to the VSCode settings and search for "noir", or click extension settings on the `noir-lang` LSP plugin.
+Update the `Noir: Nargo Path` field to point to your desired `aztec-nargo` executable.
 
 ## What's next?
 
-To deploy a smart contract to your sandbox and interact with it using Aztec.js, go to the [next page](getting_started/aztecjs-getting-started.md).
+Now you have a development network running, so you're ready to start coding your first app with Aztec.nr and Aztec.js!
 
-To skip this and write your first smart contract, go to the [Aztec.nr getting started page](getting_started/aztecnr-getting-started.md).
+To follow the series of tutorials, start with the private voting contract [here](./tutorials/contract_tutorials/private_voting_contract.md).
 
+If you want to just keep learning, you can read about the high level architecture on the [Core Components page](./aztec/concepts/state_model/index.md) and [the lifecycle of a transaction](./aztec/concepts/transactions.md).
 
diff --git a/docs/docs/getting_started/codespaces.md b/docs/docs/getting_started/codespaces.md
@@ -0,0 +1,25 @@
+---
+title: Codespaces
+sidebar_position: 0
+draft: true
+---
+
+All machines are different, and you may not want to run the sandbox locally (for example when using Windows). We thought about you exactly ❤️ 
+
+[Codespaces](https://github.com/features/codespaces) are a quick way to develop: they provision a remote machine with all tooling you need for Aztec in just a few minutes. We're big fans, so we prepared some prebuilt images to make it easier and faster.
+
+Just choose a boilerplate and click "create new codespace":
+
+[![One-Click React Starter](/img/codespaces_badges/react_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Freact%2Fdevcontainer.json) [![One-Click HTML/TS Starter](/img/codespaces_badges/vanilla_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Fvanilla%2Fdevcontainer.json) [![One-Click Token Starter](/img/codespaces_badges/token_cta_badge.svg)](https://codespaces.new/AztecProtocol/aztec-packages?devcontainer_path=.devcontainer%2Ftoken%2Fdevcontainer.json)
+
+This creates a codespace with a prebuilt image containing one of the "Aztec Boxes" and a development network (sandbox). 
+- You can develop directly on the codespace, push it to a repo, make yourself at home.
+- You can also just use the sandbox that comes with it. The URL will be logged, you just need to use it as your `PXE_URL`.
+
+You can then start, stop, or see the logs of your sandbox just by calling `sandbox` or `npx aztec-app sandbox`. Run `sandbox -h` for a list of commands.
+
+## More about codespaces
+
+Codespaces are way more powerful than you may initially think. For example, you can connect your local `vscode` to a remote codespace, for a fully contained development environment that doesn't use any of your computer resources!
+
+Visit the [codespaces documentation](https://docs.github.com/en/codespaces/overview) for more specific documentation around codespaces.
diff --git a/docs/docs/getting_started/manual_install.md b/docs/docs/getting_started/manual_install.md
@@ -0,0 +1,77 @@
+---
+title: Manual install
+sidebar_position: 1
+---
+
+You can have some more control over the sandbox by installing it manually through the underlying script used by [`npx aztec-app`](../getting_started.md).
+
+This involves some knowledge on Docker if you want to stop, restart, or detach from logs. But it also gives you better control over things such as environment variables.
+
+### Prerequisites
+
+- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm))
+- Docker (visit [this page of the Docker docs](https://docs.docker.com/get-docker/) on how to install it)
+
+### Install the sandbox
+
+To install the latest Sandbox version, run:
+
+```bash
+bash -i <(curl -s install.aztec.network)
+```
+
+This will install the following tools:
+
+- **aztec** - launches various infrastructure subsystems (sequencer, prover, pxe, etc).
+- **aztec-nargo** - aztec's build of nargo, the noir compiler toolchain.
+- **aztec-sandbox** - a wrapper around docker-compose that launches services needed for sandbox testing.
+- **aztec-up** - a tool to upgrade the aztec toolchain to the latest, or specific versions.
+- **aztec-builder** - A useful tool for projects to generate ABIs and update their dependencies.
+
+Once these have been installed, to start the sandbox, run:
+
+```bash
+aztec-sandbox
+```
+
+### Have fun
+
+**Congratulations, you have just installed and run the Aztec Sandbox!**
+
+```bash
+     /\        | |
+    /  \    ___| |_ ___  ___
+   / /\ \  |_  / __/ _ \/ __|
+  / ____ \  / /| ||  __/ (__
+ /_/___ \_\/___|\__\___|\___|
+
+```
+
+In the terminal, you will see some logs:
+
+1. Sandbox version
+2. Contract addresses of rollup contracts
+3. PXE (private execution environment) setup logs
+4. Initial accounts that are shipped with the sandbox and can be used in tests
+
+## Running Aztec PXE / Node / P2P-Bootstrap node
+
+If you wish to run components of the Aztec network stack separately, you can use the `aztec start` command with various options for enabling components.
+
+```bash
+aztec start --node [nodeOptions] --pxe [pxeOptions] --archiver [archiverOptions] --sequencer [sequencerOptions] --prover [proverOptions] ----p2p-bootstrap [p2pOptions]
+```
+
+Starting the aztec node alongside a PXE, sequencer or archiver, will attach the components to the node.Eg if you want to run a PXE separately to a node, you can [read this guide](../aztec/concepts/pxe/index.md)/
+
+## Update the sandbox
+
+To update the sandbox, you can just run:
+
+```bash
+aztec-up
+```
+
+## Next steps
+
+Visit the [sandbox reference](../reference/sandbox_reference/index.md) for more info on which environment variables you can set, which cheat codes you can use, and learn about what exactly is the Aztec Sandbox.
diff --git a/docs/docs/guides/smart_contracts/how_to_compile_contract.md b/docs/docs/guides/smart_contracts/how_to_compile_contract.md
@@ -222,7 +222,7 @@ export class TokenContract extends ContractBase {
 }
 ```
 
-Read more about interacting with contracts using `aztec.js` [here](../../getting_started/aztecjs-getting-started.md).
+Read more about interacting with contracts using `aztec.js` [here](../../tutorials/aztecjs-getting-started.md).
 
 ### Aztec.nr interfaces
 

diff --git a/docs/docs/guides/smart_contracts/writing_contracts/initializers.md b/docs/docs/guides/smart_contracts/writing_contracts/initializers.md
@@ -27,4 +27,4 @@ Initializers are commonly used to set an admin, such as this example:
 
 Here, the initializer is calling a public function. It can also call a private function. Learn more about calling functions from functions [here](./call_functions.md).
 
-To see constructors in action, check out the [Aztec.nr getting started guide](../../../getting_started/aztecnr-getting-started.md).
+To see an initializer in action, check out the [Counter Contract Tutorial](../../../tutorials/contract_tutorials/counter_contract.md).
diff --git a/docs/docs/reference/sandbox_reference/index.md b/docs/docs/reference/sandbox_reference/index.md
@@ -5,26 +5,6 @@ sidebar_position: 0
 
 The Aztec Sandbox is an environment for local development on the Aztec Network. It's easy to get setup with just a single, simple command, and contains all the components needed to develop and test Aztec contracts and applications.
 
-## Components of the Aztec network
-
-Aztec's Layer 2 network is a fully programmable combined private/public ZK rollup. To achieve this, the network contains the following primary components:
-
-- Aztec Node - Aggregates all of the 'backend' services necessary for the building and publishing of rollups. This package is currently in development and much of the functionality is mocked.
-- [Private Execution Environment (PXE)](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/pxe) - Normally residing with the end client, this decrypts and stores a client's private state, executes simulations and submits transactions to the Aztec Node.
-- [Aztec.js](https://github.com/AztecProtocol/aztec-packages/tree/master/yarn-project/aztec.js) - Aztec's client library for interacting with the PXE (think Ethers.js). See the getting started guide [here](../../getting_started/aztecjs-getting-started.md).
-
-All of this is included in the Sandbox, with the exception of Aztec.js which you can use to interact with it.
-
-With the help of Aztec.js you will be able to:
-
-- Create an account
-- Deploy a contract
-- Call view methods on contracts
-- Simulate the calling of contract functions
-- Send transactions to the network
-- Be notified when transactions settle
-- Query chain state such as chain id, block number etc.
-
 ## What's in the Sandbox?
 
 The sandbox contains a local Ethereum instance running [Anvil](https://book.getfoundry.sh/anvil/), a local instance of the Aztec rollup and an aztec private execution client for handling user transactions and state.

diff --git a/docs/docs/reference/sandbox_reference/sandbox-reference.md b/docs/docs/reference/sandbox_reference/sandbox-reference.md
@@ -8,67 +8,6 @@ For a quick start, follow the [guide](../../getting_started.md) to install the s
 
 :::
 
-## Manual Install
-
-You can manually install the sandbox via the underlying script used in the [Aztec Boxes](getting_started.md#run-the-npx-script).
-
-### Prerequisites
-
-- Node.js >= v18 (recommend installing with [nvm](https://github.com/nvm-sh/nvm))
-- Docker (visit [this page of the Docker docs](https://docs.docker.com/get-docker/) on how to install it)
-
-### Install the sandbox
-
-To install the latest Sandbox version, run:
-
-```bash
-bash -i <(curl -s install.aztec.network)
-```
-
-This will install the following tools:
-
-- **aztec** - launches various infrastructure subsystems (sequencer, prover, pxe, etc).
-- **aztec-nargo** - aztec's build of nargo, the noir compiler toolchain.
-- **aztec-sandbox** - a wrapper around docker-compose that launches services needed for sandbox testing.
-- **aztec-up** - a tool to upgrade the aztec toolchain to the latest, or specific versions.
-- **aztec-builder** - A useful tool for projects to generate ABIs and update their dependencies.
-
-Once these have been installed, to start the sandbox, run:
-
-```bash
-aztec-sandbox
-```
-
-### Have fun!
-
-**Congratulations, you have just installed and run the Aztec Sandbox!**
-
-```bash
-     /\        | |
-    /  \    ___| |_ ___  ___
-   / /\ \  |_  / __/ _ \/ __|
-  / ____ \  / /| ||  __/ (__
- /_/___ \_\/___|\__\___|\___|
-
-```
-
-In the terminal, you will see some logs:
-
-1. Sandbox version
-2. Contract addresses of rollup contracts
-3. PXE (private execution environment) setup logs
-4. Initial accounts that are shipped with the sandbox and can be used in tests
-
-## Running Aztec PXE / Node / P2P-Bootstrap node
-
-If you wish to run components of the Aztec network stack separately, you can use the `aztec start` command with various options for enabling components.
-
-```bash
-aztec start --node [nodeOptions] --pxe [pxeOptions] --archiver [archiverOptions] --sequencer [sequencerOptions] --prover [proverOptions] ----p2p-bootstrap [p2pOptions]
-```
-
-Starting the aztec node alongside a PXE, sequencer or archiver, will attach the components to the node.Eg if you want to run a PXE separately to a node, you can [read this guide](../../aztec/concepts/pxe/index.md)/
-
 ## Environment Variables
 
 There are various environment variables you can use when running the whole sandbox or when running on of the available modes.

diff --git a/...etting_started/aztecjs-getting-started.md → ...docs/tutorials/aztecjs-getting-started.md b/...etting_started/aztecjs-getting-started.md → ...docs/tutorials/aztecjs-getting-started.md
@@ -357,4 +357,4 @@ That's it! We have successfully deployed a token contract to an instance of the
 
 ## Next Steps
 
-Write your first smart contract on the [next page](./aztecnr-getting-started.md).
+Write your first account contract on the [next page](./write_accounts_contract.md).
diff --git a/docs/docs/tutorials/contract_tutorials/advanced/_category_.json b/docs/docs/tutorials/contract_tutorials/advanced/_category_.json
@@ -1,6 +1,6 @@
 {
     "label": "Advanced",
-    "position": 3,
+    "position": 5,
     "collapsible": true,
     "collapsed": true
 }
diff --git a/...etting_started/aztecnr-getting-started.md → ...ls/contract_tutorials/counter_contract.md b/...etting_started/aztecnr-getting-started.md → ...ls/contract_tutorials/counter_contract.md
@@ -1,15 +1,15 @@
 ---
-title: Writing Your First Smart Contract
-sidebar_position: 2
+title: Counter Contract
+sidebar_position: 0
 ---
 
 In this guide, we will create our first Aztec.nr smart contract. We will build a simple private counter. This contract will get you started with the basic setup and syntax of Aztec.nr, but doesn't showcase the awesome stuff Aztec is capable of.
 
-If you already have some experience with Noir and want to build a cooler contract that utilizes both private and public state, you might want to check out the [token contract tutorial instead](../tutorials/contract_tutorials/token_contract.md).
+If you already have some experience with Noir and want to build a cooler contract that utilizes both private and public state, you might want to check out the [token contract tutorial instead](../../tutorials/contract_tutorials/token_contract.md).
 
 ## Prerequisites
 
-- You have followed the [quickstart](../getting_started.md)
+- You have followed the [quickstart](../../getting_started.md)
 - Running Aztec Sandbox
 
 ## Set up a project
@@ -116,7 +116,7 @@ Let’s create a constructor method to run on deployment that assigns an initial
 
 This function accesses the counts from storage. Then it assigns the passed initial counter to the `owner`'s counter privately using `at().add()`.
 
-We have annotated this and other functions with `#[aztec(private)]` which are ABI macros so the compiler understands it will handle private inputs. Learn more about functions and annotations [here](../aztec/concepts/smart_contracts/functions/index.md).
+We have annotated this and other functions with `#[aztec(private)]` which are ABI macros so the compiler understands it will handle private inputs. Learn more about functions and annotations [here](../../aztec/concepts/smart_contracts/functions/index.md).
 
 ## Incrementing our counter
 
@@ -160,28 +160,4 @@ In the same directory, run this:
 aztec-builder codegen -o src/artifacts target
 ```
 
-You can now use the artifact and/or the TS class in your Aztec.js! If you skipped the Aztec.js getting-started guide, you can follow it [here](aztecjs-getting-started.md). This will teach you about deploying and calling contracts in Aztec.js.
-
-## Install Noir LSP (recommended)
-
-Install the [Noir Language Support extension](https://marketplace.visualstudio.com/items?itemName=noir-lang.vscode-noir) to get syntax highlighting, syntax error detection and go-to definitions for your Aztec contracts.
-
-Once the extension is installed, check your nargo binary by hovering over `Nargo` in the status bar on the bottom right of the application window. Click to choose the path to `aztec-nargo` (or regular `nargo`, if you have that installed).
-
-You can print the path of your `aztec-nargo` executable by running:
-
-```bash
-which aztec-nargo
-```
-
-To specify a custom nargo executable, go to the VSCode settings and search for "noir", or click extension settings on the `noir-lang` LSP plugin.
-Update the `Noir: Nargo Path` field to point to your desired `aztec-nargo` executable.
-
-## What's next?
-
-The next recommmended steps are follow the tutorials in order. They will teach you more about contracts, Aztec.js, and how Aztec works in general.
-
-To follow the series of tutorials, start with the private voting contract [here](../tutorials/contract_tutorials/private_voting_contract.md).
-
-Alternatively, you can read about the high level architecture on the [Core Components page](../aztec/concepts/state_model/index.md) and [the lifecycle of a transaction](../aztec/concepts/transactions.md).
-
+You can now use the artifact and/or the TS class in your Aztec.js!
diff --git a/docs/docs/tutorials/contract_tutorials/crowdfunding_contract.md b/docs/docs/tutorials/contract_tutorials/crowdfunding_contract.md
@@ -1,6 +1,6 @@
 ---
 title: "Crowdfunding contract"
-sidebar_position: 2
+sidebar_position: 3
 tags: [developers, tutorial, example]
 ---