feat(docs): DIP1 - Extracting how-tos (AztecProtocol#4251)

Closes AztecProtocol/dev-rel#110
Closes AztecProtocol#3282
Closes AztecProtocol/dev-rel#114
Closes AztecProtocol/dev-rel#116

---------

Co-authored-by: Cat McGee <catmcgee@Cats-MacBook-Pro.local>

docs/docs/developers/aztecjs/guides/call_view_function.md

@@ -0,0 +1,15 @@
+---
+title: How to Call a View Function
+---
+
+This guide explains how to call a `view` function using [Aztec.js](../main.md).
+
+To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#calling-an-unconstrained-view-function).
+
+```typescript
+import { Contract } from "@aztec/aztec.js";
+
+const contract = await Contract.at(contractAddress, MyContractArtifact, wallet);
+const balance = await contract.methods.getBalance(wallet.getAddress()).view();
+console.log(`Account balance is ${balance}`);
+```

docs/docs/developers/aztecjs/guides/create_account.md

@@ -0,0 +1,21 @@
+---
+title: How to Create a New Account
+---
+
+This guide explains how to create a new account using [Aztec.js](../main.md).
+
+To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#creating-accounts).
+
+```typescript
+import { getSchnorrAccount } from "@aztec/aztec.js";
+import { GrumpkinPrivateKey } from "@aztec/circuit-types";
+
+const encryptionPrivateKey = GrumpkinPrivateKey.random();
+const signingPrivateKey = GrumpkinPrivateKey.random();
+const wallet = getSchnorrAccount(
+  pxe,
+  encryptionPrivateKey,
+  signingPrivateKey
+).waitDeploy();
+console.log(`New account deployed at ${wallet.getAddress()}`);
+```

docs/docs/developers/aztecjs/guides/deploy_contract.md

@@ -0,0 +1,18 @@
+---
+title: How to Deploy a Contract
+---
+
+This guide explains how to deploy a smart contract using [Aztec.js](../main.md).
+
+To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#deploying-a-token-contract).
+
+```typescript
+import { Contract } from "@aztec/aztec.js";
+
+const contract = await Contract.deploy(wallet, MyContractArtifact, [
+  ...constructorArgs,
+])
+  .send()
+  .deployed();
+console.log(`Contract deployed at ${contract.address}`);
+```

docs/docs/developers/aztecjs/guides/send_transaction.md

@@ -0,0 +1,20 @@
+---
+title: How to Send a Transaction
+---
+
+This guide explains how to send a transaction using [Aztec.js](../main.md).
+
+To do this from the CLI, go [here](../../sandbox/references/cli-commands.md#sending-a-transaction).
+
+```typescript
+import { Contract } from "@aztec/aztec.js";
+
+const contract = await Contract.at(contractAddress, MyContractArtifact, wallet);
+const tx = await contract.methods
+  .transfer(amount, recipientAddress)
+  .send()
+  .wait();
+console.log(
+  `Transferred ${amount} to ${recipientAddress} on block ${tx.blockNumber}`
+);
+```

docs/docs/developers/aztecjs/main.md

@@ -2,64 +2,23 @@
 title: Aztec.js
 ---
 
-If you are looking for the API reference, go [here](../../apis/aztec-js/index.md).
+If you are looking for the Aztec.js API reference, go [here](../../apis/aztec-js/index.md).
 
 ## Introduction
-
 Aztec.js is a library that provides APIs for managing accounts and interacting with contracts on the Aztec network. It communicates with the [Private eXecution Environment (PXE)](https://docs.aztec.network/apis/pxe/interfaces/PXE) through a `PXE` implementation, allowing developers to easily register new accounts, deploy contracts, view functions, and send transactions.
 
-## Usage
-
-### Create a new account
-
-```typescript
-import { getSchnorrAccount } from "@aztec/aztec.js";
-import { GrumpkinPrivateKey } from "@aztec/circuit-types";
-
-const encryptionPrivateKey = GrumpkinPrivateKey.random();
-const signingPrivateKey = GrumpkinPrivateKey.random();
-const wallet = getSchnorrAccount(
-  pxe,
-  encryptionPrivateKey,
-  signingPrivateKey
-).waitDeploy();
-console.log(`New account deployed at ${wallet.getAddress()}`);
-```
-
-### Deploy a contract
-
-```typescript
-import { Contract } from "@aztec/aztec.js";
-
-const contract = await Contract.deploy(wallet, MyContractArtifact, [
-  ...constructorArgs,
-])
-  .send()
-  .deployed();
-console.log(`Contract deployed at ${contract.address}`);
-```
-
-### Send a transaction
+## Guides
 
-```typescript
-import { Contract } from "@aztec/aztec.js";
+- [How to create a new account](./guides/create_account.md)
+- [How to deploy a smart contract](./guides/deploy_contract.md)
+- [How to send a transaction](./guides/send_transaction.md)
+- [How to call a view function](./guides/call_view_function.md)
 
-const contract = await Contract.at(contractAddress, MyContractArtifact, wallet);
-const tx = await contract.methods
-  .transfer(amount, recipientAddress)
-  .send()
-  .wait();
-console.log(
-  `Transferred ${amount} to ${recipientAddress} on block ${tx.blockNumber}`
-);
-```
+## References
 
-### Call a view function
+- [Aztec.js Reference](../../apis/aztec-js/index.md)
+- [Accounts Reference](../../apis/accounts/index.md)
 
-```typescript
-import { Contract } from "@aztec/aztec.js";
+## Tutorials
 
-const contract = await Contract.at(contractAddress, MyContractArtifact, wallet);
-const balance = await contract.methods.getBalance(wallet.getAddress()).view();
-console.log(`Account balance is ${balance}`);
-```
+- [An example of testing with Aztec.js](../tutorials/testing.md)

docs/docs/developers/contracts/compiling.md → docs/docs/developers/contracts/compiling_contracts/how_to_compile_contract.md

@@ -1,6 +1,8 @@
-# Compiling contracts
+---
+title: How to compile a contract
+---
 
-Once you have written a [contract](../contracts/main.md) in Aztec.nr, you will need to compile it into an [artifact](./artifacts.md) in order to use it.
+Once you have written a [contract](../main.md) in Aztec.nr, you will need to compile it into an [artifact](./artifacts.md) in order to use it.
 
 In this guide we will cover how to do so, both using the CLI and programmatically.
 
@@ -10,7 +12,7 @@ We'll also cover how to generate a helper [TypeScript interface](#typescript-int
 
 To compile a contract using the Aztec's build of nargo.
 
-Run the `aztec-nargo compile` command within your [contract project folder](./layout.md#directory-structure), which is the one that contains the `Nargo.toml` file:
+Run the `aztec-nargo compile` command within your [contract project folder](../writing_contracts/layout.md), which is the one that contains the `Nargo.toml` file:
 
 ```bash
 aztec-nargo compile
@@ -111,11 +113,11 @@ 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](../../getting_started/aztecjs-getting-started.md).
 
 ### Aztec.nr interfaces
 
-An Aztec.nr contract can [call a function](./syntax/functions/main.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serializing the arguments, which is not type-safe.
+An Aztec.nr contract can [call a function](../writing_contracts/functions/call_functions.md) in another contract via `context.call_private_function` or `context.call_public_function`. However, this requires manually assembling the function selector and manually serializing the arguments, which is not type-safe.
 
 To make this easier, the compiler can generate contract interface structs that expose a convenience method for each function listed in a given contract artifact. These structs are intended to be used from another contract project that calls into the current one. For each contract, two interface structs are generated: one to be used from private functions with a `PrivateContext`, and one to be used from open functions with a `PublicContext`.
 
@@ -209,15 +211,15 @@ impl TokenPublicContextInterface {
 }
 ```
 
-Read more about how to use the Aztec.nr interfaces [here](./syntax/functions/main.md).
+Read more about how to use the Aztec.nr interfaces [here](../writing_contracts/functions/main.md).
 
 :::info
 At the moment, the compiler generates these interfaces from already compiled ABIs, and not from source code. This means that you should not import a generated interface from within the same project as its source contract, or you risk circular references.
 :::
 
 ## Next steps
 
-Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../developers/cli/main.md#deploying-a-token-contract) and [interact](../../developers/cli/main.md#sending-a-transaction) with them.
+Once you have compiled your contracts, you can use the generated artifacts via the `Contract` class in the `aztec.js` package to deploy and interact with them, or rely on the type-safe typescript classes directly. Alternatively, use the CLI [to deploy](../../sandbox/references/cli-commands.md#deploying-a-token-contract) and [interact](../../sandbox/references/cli-commands.md#calling-an-unconstrained-view-function) with them.
 
-import Disclaimer from "../../misc/common/\_disclaimer.mdx";
+import Disclaimer from "../../../misc/common/\_disclaimer.mdx";
 <Disclaimer/>

docs/docs/developers/contracts/deploying.md → docs/docs/developers/contracts/deploying_contracts/how_to_deploy_contract.md

@@ -1,12 +1,16 @@
+---
+title: How to deploy a contract
+---
+
 # Deploying contracts
 
-Once you have [compiled](./compiling.md) your contracts you can proceed to deploying them using the aztec-cli or using aztec.js which is a Typescript client to interact with the sandbox.
+Once you have [compiled](../compiling_contracts/how_to_compile_contract.md) your contracts you can proceed to deploying them using the aztec-cli or using aztec.js which is a Typescript client to interact with the sandbox.
 
 ## Prerequisites
 
-- `aztec-cli` and `aztec-nargo` installed (go to [CLI main section](../cli/main.md) for installation instructions)
-- contract artifacts ready (go to [Compiling contracts section](./compiling.md) for instructions on how to compile contracts)
-- Aztec Sandbox running (go to [Sandbox section](../getting_started/quickstart.md) for instructions on how to install and run the sandbox)
+- `aztec-cli` and `aztec-nargo` installed (go to [Sandbox and CLI section](../../sandbox/main.md) for installation instructions)
+- contract artifacts ready (go to [How to Compile Contract](../compiling_contracts/how_to_compile_contract.md) for instructions on how to compile contracts)
+- Aztec Sandbox running (go to [Sandbox section](../../getting_started/quickstart.md) for instructions on how to install and run the sandbox)
 
 ## Deploy
 
@@ -39,7 +43,7 @@ Generate the typescript class:
 aztec-cli codegen ./aztec-nargo/output/target/path -o src/artifacts --ts
 ```
 
-This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](./compiling.md).
+This would create a typescript file like `Example.ts` in `./src/artifacts`. Read more on the [compiling page](../compiling_contracts/how_to_compile_contract.md).
 
 Now you can import it to easily deploy and interact with the contract.
 
@@ -84,7 +88,7 @@ Its arguments are `PXE` client and contract constructor arguments.
 
 Additionally the `.send()` method can have a few optional arguments too, which are specified in an optional object:
 
-- `portalContract?: EthAddress`: The L1 portal address to link the contract to. See the section on [Portals to learn more about them](./portals/main.md).
+- `portalContract?: EthAddress`: The L1 portal address to link the contract to. See the section on [Portals to learn more about them](../writing_contracts/portals/portals.md).
 - `contractAddressSalt?: Fr`: A salt which is one of the inputs when computing a contract address of the contract to be deployed.
   By default is set to a random value.
   Set it, if you need a deterministic contract address (same functionality as Ethereum's `CREATE2` opcode).

docs/docs/developers/contracts/main.md

@@ -1,14 +1,18 @@
-import DocCardList from '@theme/DocCardList';
+---
+title: Smart Contracts
+---
 
-# Aztec.nr
+This section is a collection of how-to guides and references for building smart contracts with Aztec.nr. 
+
+If you are looking for an overview of how smart contracts work, head to the [Concepts section](../../learn/concepts/smart_contracts/main.md).
 
 ## What is Aztec.nr?
 
 **Aztec.nr** is a framework for writing Aztec smart contracts.
 
 ## Nomenclature
 
-[**Noir**](https://noir-lang.org/) is a domain specific language for creating and verifying proofs. It's design choices are influenced heavily by Rust.
+[**Noir**](https://noir-lang.org/) is a domain specific language for creating and verifying proofs. Its design choices are influenced heavily by Rust.
 
 A **smart contract** is just a collection of persistent state variables, and a collection of functions which may edit those state variables.
 
@@ -20,7 +24,7 @@ An **Aztec smart contract** is a smart contract with **private** state variables
 
 ## Install aztec-nargo
 
-To write an Aztec.nr contract, you need to the compiler, `aztec-nargo` which is installed when you install the sandbox. See install instructions [here](../cli/sandbox-reference.md).
+To write an Aztec.nr contract, you need to the compiler, `aztec-nargo` which is installed when you install the sandbox. See install instructions [here](../sandbox/references/sandbox-reference.md).
 
 :::info
 For those coming from vanilla Noir, the version used for aztec.nr is tracked separately to nargo for vanilla Noir. Be sure to use `aztec-nargo` to compile your contracts.
@@ -44,7 +48,7 @@ There are a number of tools to make writing Aztec.nr contracts in Noir more plea
 
 ## Tutorials
 
-See the [Token Contract tutorial](../tutorials/writing_token_contract.md) for more info on getting set up to write contracts.
+See the [Private Voting tutorial](../tutorials/writing_private_voting_contract.md) for more info on getting set up to write contracts.
 
 ## Learn more
 

docs/docs/developers/contracts/syntax/historical_access/history_lib_reference.md → docs/docs/developers/contracts/references/history_lib_reference.md

@@ -18,7 +18,11 @@ Note inclusion proves that a note existed (its hash was included in a note hash
 | block_number    | u32                    | Block number for proving note's existence           |
 | context         | PrivateContext         | Private context     |
 
-`prove_note_inclusion` takes 2 parameters:
+## prove_note_commitment_inclusion
+
+A **commitment**, also referred to as a **note hash** is a public acknowledgment of the existence of a note without revealing the content of the note. You can learn more about how to compress a note to a note hash [here](../../../learn/concepts/storage/trees/main.md#example-note).
+
+`prove_note_commitment_inclusion` takes 2 parameters:
 
 | Name            | Type                   | Description                                         |
 |-----------------|------------------------|-----------------------------------------------------|