feat(docs): Load current aztec version for aztec.nr dependencies in d…

…ocs (#2440)

Instead of pointing the user to install aztec.nr from master, we point
them to the last released version. This ensures that any unreleased
breaking changes to aztec.nr won't hit the user.


![image](https://github.com/AztecProtocol/aztec-packages/assets/429604/72447e11-6f3a-4f08-882d-ab6dda02d38a)

This requires changing the triple-backtick code block to an explicit
`<CodeBlock>` mdx component, so we can escape the content and call the
function that provides the current version. It also requires `import`ing
the function explicitly.

As a less verbose alternative, I considered using release-please for
this. We could annotate the triple-backtick block with
`x-release-please-version` comments, and have release-please
automatically replace the version there. However, there is no easy way
to test this locally, and it required explicitly adding the doc file to
an `extra-files` setting in the release config manifest, which is easy
to forget. So I went with the more verbose but more explicit version of
having to call `AztecPackagesVersion`.

build_manifest.json

@@ -90,7 +90,9 @@
     "rebuildPatterns": [
       "^docs/",
       "^.*.cpp$",
-      "^.*.ts$"
+      "^.*.ts$",
+      "^.release-please-manifest.json$",
+      "^.*/noir-version.json$"
     ]
   },
   "l1-contracts": {

docs/docs/dev_docs/contracts/syntax/main.md

@@ -18,21 +18,22 @@ Aztec.nr contains abstractions which remove the need to understand the low-level
 
 To import Aztec.nr into your Aztec contract project, simply include it as a dependency. For example:
 
-```toml
-[package]
+import { AztecPackagesVersion } from "@site/src/components/Version";
+
+<CodeBlock language="toml">{`[package]
 name = "token_contract"
 authors = [""]
 compiler_version = "0.1"
 type = "contract"
-
+ 
 [dependencies]
 # Framework import
-aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/aztec" }
-
+aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/aztec" }
+ 
 # Utility dependencies
-value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/value-note"}
-safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/safe-math"}
-```
+value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/value-note"}
+safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/safe-math"}
+`}</CodeBlock>
 
 :::info 
 Note: currently the dependency name ***MUST*** be `aztec`. The framework expects this namespace to be available when compiling into contracts. This limitation may be removed in the future.

docs/docs/dev_docs/dapps/tutorials/contract_deployment.md

@@ -17,12 +17,13 @@ nargo new --contract token
 
 Then, open the `contracts/token/Nargo.toml` configuration file, and add the `aztec.nr` and `value_note` libraries as dependencies:
 
-```toml
-[dependencies]
-aztec = { git="https://github.com/AztecProtocol/aztec-nr", tag="master", directory="aztec" }
-value_note = { git="https://github.com/AztecProtocol/aztec-nr", tag="master", directory="value-note" }
-safe_math = {  git="https://github.com/AztecProtocol/aztec-nr", tag="master", directory="safe-math" }
-```
+import { AztecPackagesVersion } from "@site/src/components/Version";
+
+<CodeBlock language="toml">{`[dependencies]
+aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/aztec" }
+value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/value-note"}
+safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/safe-math"}
+`}</CodeBlock>
 
 Last, copy-paste the code from the `Token` contract into `contracts/token/main.nr`:
 

docs/docs/dev_docs/getting_started/noir_contracts.md

@@ -59,16 +59,17 @@ Before writing the contracts, we must add the aztec.nr library. This adds smart
 
 3. Add aztec.nr library as a dependency to your noir project. Open Nargo.toml that is in the `contracts/example_contract` folder, and add the dependency section as follows:
 
-```
-[package]
+import { AztecPackagesVersion } from "@site/src/components/Version";
+
+<CodeBlock language="toml">{`[package]
 name = "example_contract"
 authors = [""]
 compiler_version = "0.1"
 type = "contract"
-
+ 
 [dependencies]
 aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/aztec" }
-```
+`}</CodeBlock>
 
 :::note
 You may need to update your dependencies depending on the contract that you are writing. For example, the token contract [imports more](../getting_started/token_contract_tutorial#project-setup).

docs/docs/dev_docs/getting_started/token_contract_tutorial.md

@@ -80,18 +80,19 @@ Your project should look like this:
 
 Add the following dependencies to your Nargo.toml file, below the package information:
 
-```toml
-[package]
+import { AztecPackagesVersion } from "@site/src/components/Version";
+
+<CodeBlock language="toml">{`[package]
 name = "token_contract"
 authors = [""]
 compiler_version = "0.1"
 type = "contract"
-
+ 
 [dependencies]
-aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/aztec" }
-value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/value-note"}
-safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="master", directory="yarn-project/aztec-nr/safe-math"}
-```
+aztec = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/aztec" }
+value_note = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/value-note"}
+safe_math = { git="https://github.com/AztecProtocol/aztec-packages/", tag="${AztecPackagesVersion()}", directory="yarn-project/aztec-nr/safe-math"}
+`}</CodeBlock>
 
 ## Contract Interface
 

docs/docusaurus.config.js

@@ -88,7 +88,17 @@ const config = {
             const noirVersion = JSON.parse(
               fs.readFileSync(noirVersionPath).toString()
             ).tag;
-            return { noir: noirVersion };
+            const aztecVersionPath = path.resolve(
+              __dirname,
+              "../.release-please-manifest.json"
+            );
+            const aztecVersion = JSON.parse(
+              fs.readFileSync(aztecVersionPath).toString()
+            )["."];
+            return {
+              noir: noirVersion,
+              "aztec-packages": `aztec-packages-v${aztecVersion}`,
+            };
           } catch (err) {
             throw new Error(
               `Error loading Noir version from noir-compiler in docusaurus build. Check load-versions in docusaurus.config.js.\n${err}`
@@ -236,6 +246,17 @@ const config = {
             className: "code-block-error-line",
             line: "this-will-error",
           },
+          // This could be used to have release-please modify the current version in code blocks.
+          // However doing so requires to manually add each md file to release-please-config.json/extra-files
+          // which is easy to forget an error prone, so instead we rely on the AztecPackagesVersion() function.
+          {
+            line: "x-release-please-version",
+            block: {
+              start: "x-release-please-start-version",
+              end: "x-release-please-end",
+            },
+            className: "not-allowed-to-be-empty",
+          },
         ],
       },
     }),

docs/src/components/Version/index.js

@@ -8,3 +8,4 @@ export default function Version({ what }) {
 }
 
 export const NoirVersion = () => Versions()["noir"];
+export const AztecPackagesVersion = () => Versions()["aztec-packages"];

docs/src/theme/MDXComponents.js

@@ -1,6 +1,9 @@
 import React from "react";
 import MDXComponents from "@theme-original/MDXComponents";
-import Version, { NoirVersion } from "@site/src/components/Version";
+import Version, {
+  NoirVersion,
+  AztecPackagesVersion,
+} from "@site/src/components/Version";
 import InstallNargoInstructions from "@site/src/components/InstallNargoInstructions";
 import CodeBlock from "@theme/CodeBlock";
 
@@ -9,6 +12,7 @@ export default {
   ...MDXComponents,
   Version,
   NoirVersion,
+  AztecPackagesVersion,
   InstallNargoInstructions,
   CodeBlock,
 };