fix: docs preprocessor line numbers and errors (#1883)

Fixes #1727 

Also fixes silent warnings that weren't being noticed, causing docs to
break (so I made it throw an error instead of a warning).

docs/docs/dev_docs/wallets/writing_an_account_contract.md

@@ -40,13 +40,9 @@ Using the `EntrypointPayload` struct is not mandatory. You can package the instr
 
 Let's go step by step into what the `entrypoint` function is doing:
 
-#include_code entrypoint-init yarn-project/noir-contracts/src/contracts/schnorr_hardcoded_account_contract/src/main.nr rust
-
-We first initialise the private function context using the provided arguments, as we do in any other function. We use a `BoundedVec` container to make it easy to collect the arguments into a single array to be hashed, but we could also have assembled it manually.
-
 #include_code entrypoint-auth yarn-project/noir-contracts/src/contracts/schnorr_hardcoded_account_contract/src/main.nr rust
 
-Next is authenticating the transaction. To do this, we serialise and Pedersen-hash the payload, which contains the instructions to be carried out along with a nonce. We then assert that the signature verifies against the resulting hash and the contract public key. This makes a transaction with an invalid signature unprovable.
+We authenticate the transaction. To do this, we serialise and Pedersen-hash the payload, which contains the instructions to be carried out along with a nonce. We then assert that the signature verifies against the resulting hash and the contract public key. This makes a transaction with an invalid signature unprovable.
 
 #include_code entrypoint-auth yarn-project/noir-contracts/src/contracts/schnorr_hardcoded_account_contract/src/main.nr rust
 

docs/src/preprocess/index.js

@@ -1,4 +1,3 @@
-const { match } = require("assert");
 const fs = require("fs");
 const path = require("path");
 
@@ -168,19 +167,10 @@ function extractCodeSnippet(filePath, identifier) {
   // We have our code snippet!
   let codeSnippet = lines.join("\n");
 
-  let startCharIndex = startMatch.index;
-  let endCharIndex = endMatch.index;
-
-  const startLine = getLineNumberFromIndex(codeSnippet, startCharIndex) + 1;
-  const endLine =
-    getLineNumberFromIndex(codeSnippet, endCharIndex) -
-    1 -
-    linesToRemove.length;
-
   // The code snippet might contain some docusaurus highlighting comments for other identifiers. We should remove those.
   codeSnippet = processHighlighting(codeSnippet, identifier);
 
-  return [codeSnippet, startLine, endLine];
+  return [codeSnippet, startLineNum, endLineNum];
 }
 
 async function processMarkdownFilesInDir(rootDir, docsDir, regex) {
@@ -207,10 +197,16 @@ async function processMarkdownFilesInDir(rootDir, docsDir, regex) {
         matchesFound = true;
         const fullMatch = match[0];
         const identifier = match[1];
-        const codeFilePath = match[2]; // Absolute path to the code file from the root of the Docusaurus project
+        let codeFilePath = match[2];
         const language = match[3];
         const opts = match[4] || "";
 
+        if (codeFilePath.slice(0) != "/") {
+          // Absolute path to the code file from the root of the Docusaurus project
+          // Note: without prefixing with `/`, the later call to `path.resolve()` gives an incorrect path (absolute instead of relative)
+          codeFilePath = `/${codeFilePath}`;
+        }
+
         const noTitle = opts.includes("noTitle");
         const noLineNumbers = opts.includes("noLineNumbers");
         const noSourceLink = opts.includes("noSourceLink");
@@ -224,10 +220,9 @@ async function processMarkdownFilesInDir(rootDir, docsDir, regex) {
             identifier
           );
 
-          const url = `https://github.com/AztecProtocol/aztec-packages/blob/master/${path.resolve(
-            rootDir,
-            codeFilePath
-          )}#L${startLine}-L${endLine}`;
+          const relativeCodeFilePath = path.resolve(rootDir, codeFilePath);
+
+          const url = `https://github.com/AztecProtocol/aztec-packages/blob/master/${relativeCodeFilePath}#L${startLine}-L${endLine}`;
 
           const title = noTitle ? "" : `title="${identifier}"`;
           const lineNumbers = noLineNumbers ? "" : "showLineNumbers";
@@ -242,14 +237,8 @@ async function processMarkdownFilesInDir(rootDir, docsDir, regex) {
           const lineNum = getLineNumberFromIndex(markdownContent, match.index);
           let wrapped_msg = `Error processing "${filePath}:${lineNum}": ${error.message}.`;
 
-          // Let's just output a warning, so we don't ruin our development experience.
-          // throw new Error(wrapped_msg);
-          console.warn(
-            "\n\x1b[33m%s\x1b[0m%s",
-            "[WARNING] ",
-            wrapped_msg,
-            "\n"
-          );
+          // We were warning here, but code snippets were being broken. So making this throw an error instead:
+          throw new Error(`${wrapped_msg}\n`);
         }
       }
 

yarn-project/aztec.js/src/account/entrypoint/index.ts

@@ -19,14 +19,12 @@ export type CreateTxRequestOpts = {
  * Knows how to assemble a transaction execution request given a set of function calls.
  */
 export interface Entrypoint {
-  // docs:start:entrypoint-interface
   /**
    * Generates an authenticated request out of set of intents
    * @param executions - The execution intents to be run.
    * @param opts - Options.
    * @returns The authenticated transaction execution request.
    */
   createTxExecutionRequest(executions: FunctionCall[], opts?: CreateTxRequestOpts): Promise<TxExecutionRequest>;
-  // docs:end:entrypoint-interface
 }
 // docs:end:entrypoint-interface