diff --git a/.github/workflows/docs-deploy.yml b/.github/workflows/docs-deploy.yml new file mode 100644 index 000000000000..c78d1ac81a9a --- /dev/null +++ b/.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 diff --git a/.github/workflows/docs-preview.yml b/.github/workflows/docs-preview.yml new file mode 100644 index 000000000000..26cae84451cc --- /dev/null +++ b/.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: "" + + - 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 }}). + + + edit-mode: replace diff --git a/.github/workflows/release-please.yml b/.github/workflows/release-please.yml index 29381c61ee41..b0632be7dfe3 100644 --- a/.github/workflows/release-please.yml +++ b/.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: | diff --git a/bootstrap.sh b/bootstrap.sh index 7f8714eb0861..80c724fe977b 100755 --- a/bootstrap.sh +++ b/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 " diff --git a/docs/README.md b/docs/README.md index 6bfa29fc9c75..7781ad716c20 100644 --- a/docs/README.md +++ b/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. diff --git a/docs/bootstrap.sh b/docs/bootstrap.sh index b77fd3695ff0..075260e05953 100755 --- a/docs/bootstrap.sh +++ b/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,55 +30,6 @@ 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 @@ -86,7 +37,7 @@ case "$cmd" in git clean -fdx ;; ""|"full"|"fast") - build_and_preview + build_docs ;; "hash") echo "$hash" @@ -94,12 +45,6 @@ case "$cmd" in "release-preview") release_preview ;; - "release") - release - ;; - "docs-release") - release - ;; *) echo "Unknown command: $cmd" exit 1 diff --git a/docs/package.json b/docs/package.json index 0c98d93141d2..20311e350e6f 100644 --- a/docs/package.json +++ b/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", diff --git a/docs/scripts/build.sh b/docs/scripts/build.sh deleted file mode 100755 index 1036de5df69d..000000000000 --- a/docs/scripts/build.sh +++ /dev/null @@ -1,64 +0,0 @@ -#!/usr/bin/env bash -set -eo pipefail - -echo "Running with ENV set to: $ENV" - -# Helper function for building packages in yarn project -build_package() { - local package_name="$1" - local build_command="${2:-yarn build}" - - echo "Building $package_name..." - (cd "yarn-project/$package_name" && $build_command) -} - -# Build script. If run on Netlify, first it needs to compile all yarn-projects -# that are involved in typedoc in order to generate their type information. -if [ -n "$NETLIFY" ]; then - # Move to project root - cd .. - echo Working dir $(pwd) - - # Make sure the latest tag is available for loading code snippets from it - LAST_TAG="v$(jq -r '.["."]' .release-please-manifest.json)" - echo Fetching latest released tag $LAST_TAG... - git fetch origin refs/tags/$LAST_TAG:refs/tags/$LAST_TAG - - # Tweak global tsconfig so we skip tests in all projects - echo Removing test files from tsconfig... - jq '. + { "exclude": ["**/*test.ts"] }' yarn-project/tsconfig.json > yarn-project/tsconfig.tmp.json - mv yarn-project/tsconfig.tmp.json yarn-project/tsconfig.json - - # Install deps (maybe we can have netlify download these automatically so they get cached..?) - echo Installing yarn-project dependencies... - (cd yarn-project && yarn) - - # Build the required projects for typedoc - build_package "pxe" - build_package "aztec.js" "yarn build:ts" - - # Back to docs site - cd docs - - # Install deps - echo Install docs deps... - yarn -fi - -# Clean -echo Cleaning... -yarn clean - -echo "Getting the versions to build..." -yarn version::stables - -# Now build the docsite -echo Building docsite... -echo "Processing..." -yarn preprocess -yarn typedoc -sh scripts/move_processed.sh - - -echo "Building..." -yarn docusaurus build diff --git a/docs/scripts/cut_version.sh b/docs/scripts/cut_version.sh deleted file mode 100755 index 4000707328cc..000000000000 --- a/docs/scripts/cut_version.sh +++ /dev/null @@ -1,16 +0,0 @@ -#!/usr/bin/env bash -set -eu - -cd $(dirname "$0")/.. - -VERSION=$1 - -# We assume that the new release tag has been made on github, so setStable.ts will add this to `versions.json`. -# We don't have a version of the docs for this release however (that's what we're doing right now!) so we need to remove it. -jq 'map(select(. != "'"$VERSION"'"))' versions.json > tmp.json && mv tmp.json versions.json - -# We need to build the docs in order to perform all necessary preprocessing. -yarn build - -# Finally cut the actual new docs version. -yarn docusaurus docs:version $VERSION diff --git a/docs/scripts/docs_preview_comment.sh b/docs/scripts/docs_preview_comment.sh deleted file mode 100755 index c9dad9c06877..000000000000 --- a/docs/scripts/docs_preview_comment.sh +++ /dev/null @@ -1,64 +0,0 @@ -#!/usr/bin/env bash -# Usage: ./docs_preview_comment.sh GITHUB_TOKEN PR_NUMBER DOCS_PREVIEW_URL -# -# Comments or updates a PR on github.com/AztecProtocol/aztec-packages -# with a docs preview link. It looks for an existing comment containing -# the marker and updates it if found, otherwise creates a new one. - -source $(git rev-parse --show-toplevel)/ci3/source_bootstrap - -github_token="${1:?Missing GitHub token}" -pr_number="${2:?Missing PR number}" -docs_preview_url="${3:?Missing docs preview URL}" - -owner="AztecProtocol" -repo="aztec-packages" -comment_mark="" -api_url="https://api.github.com" - -# Build the Markdown body -function comment_body { - local url - cat <