chore(ci): build docs on every pr (#1955)

fixes: #1952
fixes: #1908

# Overview
Makes docs rebuild on every pr, the reason for this being that the pre
processor can reference ANY code. And we were not explicitly checking
that docs builds succeeded on prs.

It only takes 4 minutes to run, and runs in isolation, so its not too
bad to run each time.

## TODO
The docs were broken by some broken links that I have not expressly
fixed, but they can be forked from this and fixed

.circleci/config.yml

@@ -972,6 +972,20 @@ jobs:
           name: "Test"
           command: cond_spot_run_test_script ./scripts/run_tests canary-build uniswap_trade_on_l1_from_l2.test.ts canary-build docker-compose-e2e-sandbox.yml
 
+  build-docs:
+    machine:
+      image: ubuntu-2004:202010-01
+    resource_class: large
+    steps:
+      - *checkout
+      - *setup_env
+      - run:
+          name: "Copy docs dockerignore"
+          command: cp docs/.dockerignore .
+      - run:
+          name: "Build docs"
+          command: build docs
+
   e2e-join:
     docker:
       - image: cimg/base:current
@@ -1232,6 +1246,7 @@ workflows:
     when:
       equal: [system, << pipeline.parameters.workflow >>]
     jobs:
+      - build-docs: *defaults
       - barretenberg-x86_64-linux-gcc: *defaults
       - barretenberg-x86_64-linux-clang: *defaults
       - barretenberg-x86_64-linux-clang-assert: *defaults
@@ -1446,4 +1461,3 @@ workflows:
             - build-deployment-canary
           <<: *deploy_defaults
 
-

build_manifest.json

@@ -122,6 +122,14 @@
     ],
     "dependencies": []
   },
+  "docs": {
+    "buildDir": ".",
+    "dockerfile": "docs/Dockerfile",
+    "rebuildPatterns": [
+      "^."
+    ],
+    "dependencies": []
+  },
   "l1-contracts": {
     "buildDir": "l1-contracts",
     "dockerfile": "Dockerfile",

docs/.dockerignore

@@ -0,0 +1,25 @@
+*.node_modules
+*.docusaurus
+*.processed-docs
+*.processed-docs-cache
+*Dockerfile
+*.CONTRIBUTING.md
+*.LICENSE
+
+# Ignore C++ object files and executables
+build/
+Debug/
+Release/
+circuits/cpp/build/
+circuits/cpp/build-wasm/
+circuits/cpp/build-coverage/
+circuits/cpp/barretenberg/
+
+# Ignore Node.js build artifacts
+*/node_modules/
+*.log
+npm-debug.log
+yarn.lock
+yarn-error.log
+package-lock.json
+dist/

docs/Dockerfile

@@ -0,0 +1,10 @@
+FROM node:18-alpine
+RUN apk update
+
+WORKDIR /usr/src
+
+COPY . .
+
+WORKDIR /usr/src/docs
+
+RUN yarn && yarn build

docs/docs/dev_docs/contracts/state_variables.md

@@ -8,7 +8,8 @@ Public state is persistent state that is _publicly visible_ to anyone in the wor
 
 For developers coming from other blockchain ecosystems (such as Ethereum), this will be a familiar concept, because there, _all_ state is _publicly visible_.
 
-Aztec public state follows an account-based model. That is, each state occupies a leaf in an account-based merkle tree: the [_public state tree_](INSERT_LINK_HERE). See [here] (INSERT_LINK_HERE) for more of the technical details.
+Aztec public state follows an account-based model. That is, each state occupies a leaf in an account-based merkle tree: the _public state tree_ (INSERT LINK HERE). See _here_ (INSERT LINK HERE) for more of the technical details.
+<!-- TODO: Insert links in the italics above -->
 
 The `PublicState<T, T_SERIALISED_LEN>` struct serves as a wrapper around conventional Noir types `T`, allowing these types to be written to and read from the public state tree.
 
@@ -90,9 +91,11 @@ For example, the following function calls the account contract before it updates
 
 In contrast to public state, private state is persistent state that is _not_ visible to the whole world. Depending on the logic of the smart contract, a _private_ state variable's current value will only be known to one entity, or a closed group of entities.
 
-The value of a private state variable can either be shared via an [encrypted log](INSERT_LINK_HERE), or offchain via web2, or completely offline: it's up to the app developer.
+The value of a private state variable can either be shared via an _encrypted log_ (INSERT_LINK_HERE), or offchain via web2, or completely offline: it's up to the app developer.
+<!-- TODO: insert link in italics above -->
 
-Aztec private state follows a utxo-based model. That is, a private state's current value is represented as one or many [notes](#notes). Each note is stored as an individual leaf in a utxo-based merkle tree: the [_private state tree_](INSERT_LINK_HERE).
+Aztec private state follows a utxo-based model. That is, a private state's current value is represented as one or many [notes](#notes). Each note is stored as an individual leaf in a utxo-based merkle tree: the _private state tree_ (INSERT_LINK_HERE).
+<!-- TODO: insert link in italics above -->
 
 To greatly simplify the experience of writing private state, Aztec.nr provides three different types of private state variable:
 
@@ -227,7 +230,8 @@ This function returns the notes the account has access to:
 
 #include_code state_vars-SetGet /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/actions.nr rust
 
-There's a limit on the maxinum number of notes this function can return at a time. Check [here](INSERT_LINK_HERE) and look for `MAX_READ_REQUESTS_PER_CALL` for the up-to-date number.
+There's a limit on the maxinum number of notes this function can return at a time. Check _here_ (INSERT_LINK_HERE) and look for `MAX_READ_REQUESTS_PER_CALL` for the up-to-date number.
+<!-- TODO: insert link in italics above -->
 
 Because of this limit, we should always consider using the second argument `NoteGetterOptions` to target the notes we need, and to reduce the time required to recursively call this function.
 
@@ -245,7 +249,7 @@ For example, the following function outputs an instance of `NoteGetterOptions`,
 
 The first value of `.select` and `.sort` is the index of a field in a note type. For the note type `CardNote` that has the following fields:
 
-#include_code state_vars-CardNote /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/types/card.nr rust
+#include_code state_vars-CardNote /yarn-project/noir-contracts/src/contracts/docs_example_contract/src/types/card_note.nr rust
 
 The indices are: 0 for `points`, 1 for `secret`, and 2 for `owner`.
 

docs/package.json

@@ -19,10 +19,10 @@
     "update-specs": "./scripts/update_specs.sh"
   },
   "dependencies": {
-    "@docusaurus/core": "^2.3.1",
-    "@docusaurus/plugin-ideal-image": "^2.3.1",
-    "@docusaurus/preset-classic": "^2.3.1",
-    "@docusaurus/theme-mermaid": "^2.3.1",
+    "@docusaurus/core": "^2.4.1",
+    "@docusaurus/plugin-ideal-image": "^2.4.1",
+    "@docusaurus/preset-classic": "^2.4.1",
+    "@docusaurus/theme-mermaid": "^2.4.1",
     "@mdx-js/react": "^1.6.22",
     "axios": "^1.4.0",
     "clsx": "^1.1.1",
@@ -35,7 +35,7 @@
     "remark-math": "3"
   },
   "devDependencies": {
-    "@docusaurus/module-type-aliases": "^2.3.1",
+    "@docusaurus/module-type-aliases": "^2.4.1",
     "@tsconfig/docusaurus": "^1.0.5",
     "concurrently": "^8.0.1",
     "nodemon": "^3.0.1",