From a060ef268821a145f50dc78fd0a09821f0426ab6 Mon Sep 17 00:00:00 2001 From: iAmMichaelConnor Date: Wed, 30 Aug 2023 13:02:50 +0000 Subject: [PATCH 1/2] fix: docs preprocessor line numbers and errors --- .../wallets/writing_an_account_contract.md | 6 +-- docs/src/preprocess/index.js | 40 ++++++++----------- .../aztec.js/src/account/entrypoint/index.ts | 2 - 3 files changed, 17 insertions(+), 31 deletions(-) diff --git a/docs/docs/dev_docs/wallets/writing_an_account_contract.md b/docs/docs/dev_docs/wallets/writing_an_account_contract.md index c2f3fcd1560..a305e0015c1 100644 --- a/docs/docs/dev_docs/wallets/writing_an_account_contract.md +++ b/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 diff --git a/docs/src/preprocess/index.js b/docs/src/preprocess/index.js index 49aa627515c..590ee8256da 100644 --- a/docs/src/preprocess/index.js +++ b/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,15 @@ 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 + codeFilePath = `/${codeFilePath}`; + } + const noTitle = opts.includes("noTitle"); const noLineNumbers = opts.includes("noLineNumbers"); const noSourceLink = opts.includes("noSourceLink"); @@ -224,10 +219,13 @@ 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); + + // console.log(rootDir); + // console.log("cfp", codeFilePath); + console.log(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 +240,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`); } } diff --git a/yarn-project/aztec.js/src/account/entrypoint/index.ts b/yarn-project/aztec.js/src/account/entrypoint/index.ts index 5a6cae18cb7..0b0335b28e1 100644 --- a/yarn-project/aztec.js/src/account/entrypoint/index.ts +++ b/yarn-project/aztec.js/src/account/entrypoint/index.ts @@ -19,7 +19,6 @@ 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. @@ -27,6 +26,5 @@ export interface Entrypoint { * @returns The authenticated transaction execution request. */ createTxExecutionRequest(executions: FunctionCall[], opts?: CreateTxRequestOpts): Promise; - // docs:end:entrypoint-interface } // docs:end:entrypoint-interface From cac3298ef6af16f5589405ebb8a153bce507cff1 Mon Sep 17 00:00:00 2001 From: Michael Connor Date: Wed, 30 Aug 2023 23:02:20 +0100 Subject: [PATCH 2/2] Apply suggestions from code review --- docs/src/preprocess/index.js | 5 +---- 1 file changed, 1 insertion(+), 4 deletions(-) diff --git a/docs/src/preprocess/index.js b/docs/src/preprocess/index.js index 590ee8256da..f52e5da4063 100644 --- a/docs/src/preprocess/index.js +++ b/docs/src/preprocess/index.js @@ -203,6 +203,7 @@ async function processMarkdownFilesInDir(rootDir, docsDir, regex) { 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}`; } @@ -221,10 +222,6 @@ async function processMarkdownFilesInDir(rootDir, docsDir, regex) { const relativeCodeFilePath = path.resolve(rootDir, codeFilePath); - // console.log(rootDir); - // console.log("cfp", codeFilePath); - console.log(path.resolve(rootDir, codeFilePath)); - const url = `https://github.com/AztecProtocol/aztec-packages/blob/master/${relativeCodeFilePath}#L${startLine}-L${endLine}`; const title = noTitle ? "" : `title="${identifier}"`;