syncing

.github/workflows/ci.yml

@@ -357,7 +357,7 @@ jobs:
           concurrency_key: docs-preview-x86
       - name: "Docs Preview"
         timeout-minutes: 40
-        run: earthly-ci --no-output ./docs/+deploy-preview --PR=${{ github.event.number }} --AZTEC_BOT_COMMENTER_GITHUB_TOKEN=${{ secrets.AZTEC_BOT_GITHUB_TOKEN }} --NETLIFY_AUTH_TOKEN=${{ secrets.NETLIFY_AUTH_TOKEN }} --NETLIFY_SITE_ID=${{ secrets.NETLIFY_SITE_ID }}
+        run: earthly-ci --no-output ./docs/+deploy-preview --ENV=staging --PR=${{ github.event.number }} --AZTEC_BOT_COMMENTER_GITHUB_TOKEN=${{ secrets.AZTEC_BOT_GITHUB_TOKEN }} --NETLIFY_AUTH_TOKEN=${{ secrets.NETLIFY_AUTH_TOKEN }} --NETLIFY_SITE_ID=${{ secrets.NETLIFY_SITE_ID }}
 
   bb-bench:
     runs-on: ubuntu-latest

docs/Earthfile

@@ -10,7 +10,7 @@ deps:
   RUN yarn install --frozen-lockfile
 
 build:
-  ARG ENVIRONMENT
+  ARG ENV
   BUILD ../yarn-project/+build-dev
   BUILD ../+release-meta
   FROM +deps
@@ -21,7 +21,7 @@ build:
   SAVE ARTIFACT build
 
 serve:
-  ARG ENVIRONMENT
+  ARG ENV
   FROM +deps
   COPY +build/build build
   COPY ./static static
@@ -36,7 +36,7 @@ serve:
 
 deploy-preview:
   BUILD ../yarn-project/+scripts-prod
-  ARG ENVIRONMENT
+  ARG ENV
   ARG NETLIFY_AUTH_TOKEN
   ARG NETLIFY_SITE_ID
   ARG AZTEC_BOT_COMMENTER_GITHUB_TOKEN
@@ -45,7 +45,7 @@ deploy-preview:
   COPY --dir ../yarn-project/+scripts-prod/usr/src/yarn-project /usr/src
   COPY ./netlify.toml .
   COPY ./deploy_preview.sh .
-  RUN echo "NETLIFY_AUTH_TOKEN=$NETLIFY_AUTH_TOKEN NETLIFY_SITE_ID=$NETLIFY_SITE_ID ./deploy_preview.sh $PR $AZTEC_BOT_COMMENTER_GITHUB_TOKEN"
+  RUN NETLIFY_AUTH_TOKEN=$NETLIFY_AUTH_TOKEN NETLIFY_SITE_ID=$NETLIFY_SITE_ID ./deploy_preview.sh $PR $AZTEC_BOT_COMMENTER_GITHUB_TOKEN
 
 deploy-prod:
   BUILD ../yarn-project/+scripts-prod

docs/README.md

@@ -5,7 +5,13 @@ Documentation for the Aztec Network, built with docusaurus
 
 You can view the latest successful build here: https://docs.aztec.network
 
-## Files
+## Docusaurus
+
+This website is built using [Docusaurus 3](https://docusaurus.io/), a modern static website generator.
+
+### Files
+
+Here are the most relevant files you should be aware of:
 
 - `.gitignore` - This specifies which files Git should ignore when committing and pushing to remote repositories.
 - `docusaurus.config.js` - This is the configuration file for Docusaurus. You can manage the links in the header and footer, and site metadata here. A more in-depth introduction to this configuration file is available on the [Docusaurus website](https://docusaurus.io/docs/configuration) and full documentation for the API is [here](https://docusaurus.io/docs/docusaurus.config.js).
@@ -15,52 +21,61 @@ You can view the latest successful build here: https://docs.aztec.network
 
 The .md files in the `docs/` directory are the docs. See the [Docusaurus website](https://docusaurus.io/docs/docs-introduction) for the full documentation on how to create docs and to manage the metadata.
 
-## Contributing
-
-We welcome contributions from the community. Please review our [contribution guidelines](CONTRIBUTING.md) for more information.
-
-## Docusaurus
-
-This website is built using [Docusaurus 2](https://docusaurus.io/), a modern static website generator.
-
 ### Installation
 
+To install the dependencies and dev dependencies, run:
+
 ```
 $ yarn
 ```
 
 ### Development
 
-#### Locally
+Aztec docs pull some code from the rest of the repository. This allows for great flexibility and maintainability. Some documentation is also autogenerated.
+
+For that reason, there's a preprocessing step. You can run that step ad-hoc with `yarn preprocess` or `yarn preprocess:dev` if you want it to stay running and watching for changes.
 
-To build; serve to `localhost:3000`; and watch for changes:
+This step does the following:
+- Pulls the code from the source files using the `#include` macros explained below.
+- Autogenerates documentation using the scripts in the `src` file.
+- Puts the final documentation in a `processed-docs` folder.
+
+> [!NOTE]
+> You likely want to benefit from webpack's hot reload, which allows you to immediately see your changes when you develop on the docs. For this reason, the `yarn dev` commands will add the `ENV=dev` environment variable, which makes docusaurus serve the `docs folder` instead of the `processed docs`.
+> If you're making changes to included code or aztec.nr reference, you can run `yarn docs` instead.
+
+#### Run locally
+
+To run docusaurus development server and use hot reload (watch for changes), run:
 
 ```
-$ yarn start:dev:local
+$ yarn dev:local
 ```
 
-#### Remotely (on mainframe)
+#### Run remotely (on mainframe)
 
-To build; serve to `localhost:3000`; and watch for changes:
+It's common for developers to work on codespaces or other remote targets. For this you need to expose your development server. This is common enough to be the default development command:
 
 ```
-$ yarn start:dev
+$ yarn dev
 ```
 
-This command preprocesses `#include_code` macros, then builds the html, then starts a local development server and opens up a browser window (at `localhost:3000`, by default).
-Most changes are reflected live without having to restart the server.
-
 ### Build
 
+To build the final version of the docs (which includes processes not present in dev, like broken links checking and minification), you can run:
+
 ```
 $ yarn build
 ```
 
-This command generates static content into the `build` directory and can be served using any static contents hosting service. When run on Netlify, it will also build the typescript projects needed for extracting type information via typedoc.
-
+This command runs the preprocess command, generates static content into the `build` directory and can be served using any static contents hosting service.
 
 ## Macros
 
+As mentioned above, Aztec docs pull code from the source files. This makes it easy to include sections of the source code in tutorials and other examples.
+
+This is done via macros which are processed in the `process` step described above.
+
 ### `#include_code`
 
 You can embed code snippets into a `.md`/`.mdx` file from code which lives elsewhere in the repo.
@@ -133,3 +148,7 @@ Alternatively, you can also use the `AztecPackagesVersion()` js function, which
 import { AztecPackagesVersion } from "@site/src/components/Version";
 <>{AztecPackagesVersion()}</>
 ```
+
+## Contributing
+
+We welcome contributions from the community. Please review our [contribution guidelines](CONTRIBUTING.md) for more information.

docs/docs/reference/reference/sandbox_reference/sandbox-reference.md

@@ -6,6 +6,7 @@ title: Sandbox Reference
 
 For a quick start, follow the [guide](/getting_started/getting_started) to install the sandbox.
 
+:::
 
 ## Manual Install
 
@@ -109,57 +110,6 @@ In the terminal, you will see some logs:
 4. Initial accounts that are shipped with the sandbox and can be used in tests
 
 
-## Manual Install
-
-You can manually install the sandbox via the underlying script used in the [Aztec Boxes](getting_started/getting_started/index.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.

docs/docusaurus.config.js

@@ -46,7 +46,7 @@ const config = {
       /** @type {import('@docusaurus/preset-classic').Options} */
       {
         docs: {
-          path: process.env.HOT ? "processed-docs" : "docs",
+          path: process.env.ENV === "dev" ? "docs" : "processed-docs",
           sidebarPath: "./sidebars.js",
           editUrl: (params) => {
             return (
@@ -169,7 +169,7 @@ const config = {
     // ["./src/plugins/plugin-embed-code", {}],
   ],
   customFields: {
-    MATOMO_ENV: process.env.ENVIRONMENT || process.env.ENV,
+    MATOMO_ENV: process.env.ENV,
   },
   themeConfig:
     /** @type {import('@docusaurus/preset-classic').ThemeConfig} */

docs/package.json

@@ -4,8 +4,8 @@
   "private": true,
   "scripts": {
     "docs": "yarn preprocess && yarn typedoc && docusaurus start --host ${HOST:-localhost}",
-    "start": "HOST=0.0.0.0 ENV=dev yarn docs",
-    "start:local": "ENV=dev HOT=false yarn docs",
+    "dev": "HOST=0.0.0.0 ENV=dev yarn docs",
+    "dev:local": "ENV=dev yarn docs",
     "build": "./scripts/build.sh",
     "swizzle": "docusaurus swizzle",
     "clear": "rm -rf 'processed-docs' 'processed-docs-cache' docs/apis && docusaurus clear && rm 'src/preprocess/AztecnrReferenceAutogenStructure.json' && rm -rf 'docs/developers/references/aztec-nr'",

docs/scripts/build.sh

@@ -1,8 +1,7 @@
 #!/usr/bin/env bash
 set -eo pipefail
 
-echo "Running with ENVIRONMENT set to: $ENVIRONMENT"
-ENV=$ENVIRONMENT
+echo "Running with ENV set to: $ENV"
 
 # Helper function for building packages in yarn project
 build_package() {