chore(docs): docs versioning

.github/workflows/docs-deploy.yml

@@ -0,0 +1,52 @@
+name: Docs Deploy
+
+on:
+  workflow_dispatch:
+  push:
+    branches:
+      - master
+    paths:
+      - docs/**
+
+jobs:
+  docs-pr:
+    runs-on: ubuntu-latest
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "18"
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Build dependencies
+        run: |
+          for project in noir barretenberg l1-contracts yarn-project; do
+            $project/bootstrap.sh
+          done
+
+      # Making the bash script here so we don't accidentally deploy
+      - name: Deploy docs
+        working-directory: ./docs
+        run: |
+          echo "deploying docs to prod"
+          yarn install
+          yarn build
+
+          if ! deploy_output=$(yarn netlify deploy --site aztec-docs-dev --prod 2>&1); then
+            echo "Netlify deploy failed with error:"
+            echo "$deploy_output"
+            exit 1
+          fi

.github/workflows/docs-preview.yml

@@ -0,0 +1,93 @@
+name: Docs Preview
+
+on:
+  workflow_dispatch:
+  pull_request:
+    types: [opened, synchronize, reopened, ready_for_review, labeled]
+    paths:
+      - docs/**
+
+permissions:
+  contents: read
+  pull-requests: write
+  issues: write
+
+jobs:
+  docs-preview:
+    runs-on: ubuntu-latest
+    env:
+      AWS_ACCESS_KEY_ID: ${{ secrets.AWS_ACCESS_KEY_ID }}
+      AWS_SECRET_ACCESS_KEY: ${{ secrets.AWS_SECRET_ACCESS_KEY }}
+      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+      NETLIFY_SITE_ID: ${{ secrets.NETLIFY_SITE_ID }}
+      NETLIFY_AUTH_TOKEN: ${{ secrets.NETLIFY_AUTH_TOKEN }}
+    steps:
+      - name: Checkout code
+        uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+
+      - name: Set up Node.js
+        uses: actions/setup-node@v3
+        with:
+          node-version: "18"
+
+      - name: Enable Corepack
+        run: corepack enable
+
+      - name: Configure Git
+        run: |
+          git config --global user.name AztecBot
+          git config --global user.email tech@aztecprotocol.com
+
+      - name: Build dependencies
+        run: |
+          for project in noir barretenberg l1-contracts yarn-project; do
+            $project/bootstrap.sh
+          done
+
+      # Making the bash script here so we don't accidentally deploy
+      - name: Run release-preview script
+        working-directory: ./docs
+        run: |
+          echo "docs release preview"
+          yarn install
+          yarn build
+
+          if ! deploy_output=$(yarn netlify deploy --site aztec-docs-dev 2>&1); then
+            echo "Netlify deploy failed with error:"
+            echo "$deploy_output"
+            exit 1
+          fi
+
+          # Extract preview URL.
+          docs_preview_url=$(echo "$deploy_output" | grep -E "https://.*aztec-docs-dev.netlify.app" | awk '{print $4}')
+          if [ -z "$docs_preview_url" ]; then
+            echo "Failed to extract preview URL from Netlify output."
+          else
+            echo "Docs preview URL: ${docs_preview_url}"
+            echo "docs_preview_url=${docs_preview_url}" >> $GITHUB_ENV
+          fi
+
+      - name: Find Comment
+        uses: peter-evans/find-comment@v2
+        id: find-comment
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        with:
+          issue-number: ${{ github.event.pull_request.number }}
+          comment-author: "github-actions[bot]"
+          body-includes: "<!-- AUTOGENERATED DOCS COMMENT -->"
+
+      - name: Create or Update Comment
+        uses: peter-evans/create-or-update-comment@v3
+        if: github.event_name == 'pull_request' && github.event.pull_request.head.repo.full_name == github.repository
+        with:
+          comment-id: ${{ steps.find-comment.outputs.comment-id }}
+          issue-number: ${{ github.event.pull_request.number }}
+          token: ${{ secrets.GITHUB_TOKEN }}
+          body: |
+            # Docs Preview
+            You can check your [preview here](${{ env.docs_preview_url }}).
+
+            <!-- AUTOGENERATED DOCS COMMENT -->
+          edit-mode: replace

.github/workflows/release-please.yml

@@ -29,6 +29,8 @@ jobs:
 
   update-docs:
     name: Update docs
+    env:
+      GITHUB_TOKEN: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
     needs: [release-please]
     if: ${{ needs.release-please.outputs.release-pr }}
     runs-on: ubuntu-latest
@@ -38,19 +40,33 @@ jobs:
         uses: actions/checkout@v4
         with:
           ref: ${{ env.BRANCH_NAME  }}
-          token: ${{ secrets.AZTEC_BOT_GITHUB_TOKEN }}
 
       - name: Run corepack enable
         run: corepack enable
 
-      - name: Cut a new version
+      - name: Configure Git
+        run: |
+          git config --global user.name AztecBot
+          git config --global user.email tech@aztecprotocol.com
+
+      - name: Build dependencies
+        run: |
+          for project in noir barretenberg l1-contracts yarn-project; do
+            $project/bootstrap.sh
+          done
+
+      - name: Cut version
         working-directory: ./docs
-        run: yarn run version ${{ env.BRANCH_NAME }}
+        run: |
+          echo "[]" > versions.json
+          yarn
+          yarn build
+          yarn docusaurus docs:version ${{ env.BRANCH_NAME }}
 
-      - name: Configure git
+      - name: Filter
+        working-directory: ./docs
         run: |
-          git config --global user.email "tech@aztecprotocol.com"
-          git config --global user.name "AztecBot"
+          yarn filter-versions
 
       - name: Commit new documentation version
         run: |

bootstrap.sh

@@ -196,8 +196,7 @@ function build {
     yarn-project
     boxes
     playground
-    # Blocking release.
-    # docs
+    docs
     release-image
     aztec-up
   )
@@ -269,8 +268,7 @@ function release {
     boxes
     aztec-up
     playground
-    # Blocking release.
-    # docs
+    docs
     release-image
   )
   if [ $(arch) == arm64 ]; then
@@ -338,10 +336,6 @@ case "$cmd" in
   test|test_cmds|bench|release|release_dryrun)
     $cmd "$@"
     ;;
-  "docs-release")
-    build
-    docs/bootstrap.sh docs-release
-    ;;
   *)
     echo "Unknown command: $cmd"
     echo "usage: $0 <clean|check|fast|full|test_cmds|test|ci|release>"

docs/README.md

@@ -149,6 +149,22 @@ import { AztecPackagesVersion } from "@site/src/components/Version";
 <>{AztecPackagesVersion()}</>
 ```
 
+## Versioning
+
+Aztec Docs are versioned. Every version known is literally a copy of the website, and is in `versioned_docs` (sidebars are in `versioned_sidebars`). Seems silly but it's not: it allows you to hot-fix previous versions.
+
+The way docs builds work is the following:
+
+- [This Github Action](../.github/workflows/docs-deploy.yml) runs on merge to master, builds the dependencies needed to build the docs, then deploys on the main docs website
+- [This Github Action](../.github/workflows/docs-preview.yml) runs on pull requests if they have any docs change, and quite similarly builds the dependencies and the docs, then gives you a nice preview so you can check that everything is alright
+- [This Github Action](../.github/workflows/release-please.yml) is Release-Please, a framework made to organize different commits into releases. When it merges to master, it runs. When it runs, it builds the dependencies and cuts a new version of the docs, with the same tag that is being released
+
+### How do I change the versions that show in the website
+
+When docusaurus builds, it looks for the `versions.json` file, and builds the versions in there, together with the version in `docs`.
+
+When release-please merges, it also checks for the versions we want: the latest non-alpha-testnet, and the latest alpha-testnet. It writes those to versions.json.
+
 ## Contributing
 
 We welcome contributions from the community. Please review our [contribution guidelines](CONTRIBUTING.md) for more information.

docs/bootstrap.sh

@@ -18,7 +18,7 @@ if semver check $REF_NAME; then
   export COMMIT_TAG=$REF_NAME
 fi
 
-function build_and_preview {
+function build_docs {
   if [ "${CI:-0}" -eq 1 ] && [ $(arch) == arm64 ]; then
     echo "Not building docs for arm64 in CI."
     return
@@ -30,76 +30,21 @@ function build_and_preview {
   npm_install_deps
   denoise "yarn build"
   cache_upload docs-$hash.tar.gz build
-
-  if [ "${CI:-0}" -eq 1 ] && [ "$(arch)" == "amd64" ]; then
-    # Included as part of build step so we can skip this consistently if the build was cached.
-    release_preview
-  fi
-}
-
-# If we're an AMD64 CI run and have a PR, do a preview release.
-function release_preview {
-  echo_header "docs release preview"
-
-  # Deploy and capture exit code and output.
-  if ! deploy_output=$(yarn netlify deploy --site aztec-docs-dev 2>&1); then
-    echo "Netlify deploy failed with error:"
-    echo "$deploy_output"
-    exit 1
-  fi
-
-  # Extract preview URL.
-  local docs_preview_url=$(echo "$deploy_output" | grep -E "https://.*aztec-docs-dev.netlify.app" | awk '{print $4}')
-  if [ -z "$docs_preview_url" ]; then
-    echo "Failed to extract preview URL from Netlify output."
-  else
-    echo "Docs preview URL: ${docs_preview_url}"
-  fi
-
-  local pr_number=$(gh pr list --head "$REF_NAME" --json number --jq '.[0].number')
-  if [ -n "$pr_number" ]; then
-    if [ -z "${GITHUB_TOKEN:-}" ]; then
-      echo_stderr "Not updating docs preview comment; no PR number."
-      return
-    fi
-    # We remove color from the URL before passing.
-    scripts/docs_preview_comment.sh $GITHUB_TOKEN $pr_number "$(echo $docs_preview_url | sed -r 's/\x1B\[[0-9;]*[a-zA-Z]//g')"
-  fi
-}
-
-function release {
-  echo_header "docs release"
-
-  # If we download cached docs, we may not have netlify CLI in node_modules. Install in case.
-  yarn install
-
-  if [ $(dist_tag) != "latest" ]; then
-    # TODO attach to github release
-    do_or_dryrun yarn netlify deploy --site aztec-docs-dev
-  else
-    do_or_dryrun yarn netlify deploy --site aztec-docs-dev --prod
-  fi
 }
 
 case "$cmd" in
   "clean")
     git clean -fdx
     ;;
   ""|"full"|"fast")
-    build_and_preview
+    build_docs
     ;;
   "hash")
     echo "$hash"
     ;;
   "release-preview")
     release_preview
     ;;
-  "release")
-    release
-    ;;
-  "docs-release")
-    release
-    ;;
   *)
     echo "Unknown command: $cmd"
     exit 1

docs/package.json

@@ -6,16 +6,15 @@
     "docs": "yarn preprocess && yarn typedoc && docusaurus start --host ${HOST:-localhost}",
     "dev": "HOST=0.0.0.0 ENV=dev SHOW_PROTOCOL_SPECS=true yarn docs",
     "dev:local": "ENV=dev SHOW_PROTOCOL_SPECS=true yarn docs",
-    "build": "./scripts/build.sh",
+    "build": "yarn preprocess && yarn typedoc && yarn preprocess:move && docusaurus build",
     "swizzle": "docusaurus swizzle",
     "clean": "./scripts/clean.sh",
     "serve": "docusaurus serve",
     "preprocess": "yarn node -r dotenv/config ./src/preprocess/index.js  && node src/preprocess/generate_aztecnr_reference.js",
-    "preprocess:dev": "nodemon --config nodemon.json ./src/preprocess/index.js  && nodemon --config nodemon.json src/preprocess/generate_aztecnr_reference.js ",
-    "typedoc": "docusaurus generate-typedoc",
-    "rewrite": "node ./scripts/rewrite_paths.js",
-    "version::stables": "node ./scripts/setStable.js",
-    "version": "./scripts/cut_version.sh"
+    "preprocess:dev": "nodemon --config nodemon.json ./src/preprocess/index.js  && nodemon --config nodemon.json src/preprocess/generate_aztecnr_reference.js",
+    "preprocess:move": "sh scripts/move_processed.sh",
+    "filter-versions": "node scripts/filterVersions.js",
+    "typedoc": "docusaurus generate-typedoc"
   },
   "dependencies": {
     "@babel/runtime": "^7.26.0",