chore(docs): spinning out bb docs by signorecello · Pull Request #9402 · noir-lang/noir

signorecello · 2025-08-05T14:32:35Z

Summary

Spins off Barretenberg documentation (soon in barretenberg.aztec.network). Adds some links so devs still have the continuity in their learning journey
Adds documentation for using Noir with Aztec's devcontainer features
Implements a Playwright testing framework for the browser tutorial
Fixes broken markdown links and other nits

Key Changes

🏗️ New Dev Container Documentation

Added: docs/tooling/devcontainer.md - Guide for using Noir with Dev Containers and GitHub Codespaces
Includes setup instructions, configuration examples, and troubleshooting tips
References Aztec's Noir Dev Container feature
Links to tiny-noir-codespace example repository

🧪 Playwright Browser Testing Infrastructure

Added: Playwright test suite at tests/browser.test.ts
Added: Browser fixture application in tests/fixtures/browser/ so it can be referenced with #include_code macros and yet be tested
Updated: package.json with new test scripts:
- test:tutorial: Builds fixture and runs Playwright tests
- test: Alias for tutorial test
Added: Playwright dependencies and updated .gitignore

🔗 Barretenberg Documentation

Fixed: Shell completions link in noir_installation.md
Moved: Documentation that will be in the BB documentation, such as:
- how-to-recursion.md
- explainer-recursion.md
- how-to-solidity-verifier.mdx

🛠️ Code Documentation Integration

Enhanced: include_code.js preprocessing script to support HTML comment syntax () in addition to // and # comments
Updated: Tutorial documentation in noirjs_app.md to use #include_code directives that reference the new browser fixture
Reorganized: Moved shell completions documentation from getting_started/ to tooling/ directory

🧹 Content Cleanup

Simplified: quick_start.md by removing redundant proving backend setup (now references external docs)
Removed: Large video file (codespaces_showcase.mp4) and unused documentation files
Updated: Sidebar configuration to reflect documentation reorganization

signorecello · 2025-08-05T14:33:05Z

making this a draft until we have the BB docs

docs/tests/browser.test.ts

github-actions · 2025-08-05T14:47:26Z

🚀 Deployed on https://68acc56b70205d70e6265a84--noir-docs.netlify.app

github-actions

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Test Suite Duration'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: `ccd00bb`	Previous: `676352d`	Ratio
`test_report_zkpassport_noir-ecdsa_`	`2` s	`1` s	`2`

This comment was automatically generated by workflow using github-action-benchmark.

CC: @TomAFrench

.github/workflows/docs-test.yml

socket-security · 2025-08-18T10:50:39Z

Review the following changes in direct dependencies. Learn more about Socket for GitHub.

Diff	Package	Supply Chain Security	Vulnerability	Quality	Maintenance	License
	escape-string-regexp@4.0.0
	json-schema-traverse@0.4.1
	fast-diff@1.3.0
	clsx@1.2.1
	argparse@2.0.1
	minimatch@5.1.6 ⏵ 3.1.2
	ansi-styles@4.3.0
	ajv@6.12.6
	is-glob@4.0.3
	brace-expansion@1.1.11
	strip-json-comments@3.1.1
	p-limit@3.1.0
	chalk@5.4.1

View full report

github-actions

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Compilation Time'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: `a770763`	Previous: `7bda502`	Ratio
`rollup-root`	`1.854` s	`1.534` s	`1.21`

This comment was automatically generated by workflow using github-action-benchmark.

CC: @TomAFrench

docs/tests/fixtures/browser/target/circuit.json

docs/tests/browser.test.ts

docs/package.json

.github/workflows/docs-pr.yml

docs/docs/getting_started/quick_start.md

docs/docs/tutorials/noirjs_app.md

Savio-Sou · 2025-08-19T14:13:29Z

We should add easily accessible links in the sidebar that link to the migrated how-to guides in Barretenberg's docs.

This eases Noir users' discoveries and learning of these powerful Barretenberg features (verifying with Solidity, using bb.js, recursive proof aggregation, and any that is coming up) that they would very likely enjoy using.

Perhaps as:

- How To Guides
  - Using Barretenberg
    - Generate a Solidity Verifier (link)
    - Barretenberg on the browser (link)
    - Recursive Aggregation (link)

signorecello · 2025-08-19T15:46:34Z

We should add easily accessible links in the sidebar that link to the migrated how-to guides in Barretenberg's docs.

This eases Noir users' discoveries and learning of these powerful Barretenberg features (verifying with Solidity, using bb.js, recursive proof aggregation, and any that is coming up) that they would very likely enjoy using.

Perhaps as:
- How To Guides
  - Using Barretenberg
    - Generate a Solidity Verifier (link)
    - Barretenberg on the browser (link)
    - Recursive Aggregation (link)

Yes this would make sense, that way we don't mess too much with the structure of the sidebar. I'll do it

Co-authored-by: Savio <72797635+Savio-Sou@users.noreply.github.com>

github-actions

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Execution Time'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 1.20.

Benchmark suite	Current: `12dc720`	Previous: `110cb99`	Ratio
`private-kernel-inner`	`0.017` s	`0.014` s	`1.21`

This comment was automatically generated by workflow using github-action-benchmark.

CC: @TomAFrench

signorecello · 2025-08-19T17:15:43Z

GTG @Savio-Sou @TomAFrench changes applied

examples/docs_tutorials/browser/test.sh

TomAFrench

Looks good to me from a testing/CI perspective. One last nit and I'll leave the rest to devrel to review.

critesjosh

from the PR description, looks like the devcontainer stuff was removed?

Added: docs/tooling/devcontainer.md - Guide for using Noir with Dev Containers and GitHub Codespaces

can you update the description? we have LLMs parsing our PR descriptions now so accuracy is even more important 🙂

otherwise lgtm

Edit: disregard, looks like its there and I missed it

Savio-Sou · 2025-08-20T20:05:04Z

@signorecello looks like a browser test is failing.

github-actions · 2025-08-25T20:20:51Z

FYI @noir-lang/developerrelations on Noir doc changes.

Automated pull of nightly from the [noir](https://github.com/noir-lang/noir) programming language, a dependency of Aztec. BEGIN_COMMIT_OVERRIDE chore: remove duplicated frontend tests (noir-lang/noir#9706) chore: remove playwright workaround (noir-lang/noir#9704) fix(licm): Use `Loop::header` in `Loop::is_fully_executed` (noir-lang/noir#9700) chore: show which type is invalid as program input (noir-lang/noir#9701) chore: bump deps (noir-lang/noir#9698) chore: bump external pinned commits (noir-lang/noir#9693) chore(licm): Break things up further in LICM (noir-lang/noir#9683) chore(docs): spinning out bb docs (noir-lang/noir#9402) fix(ssa)!: Signed shift overflow checks rhs < bit_size (noir-lang/noir#9685) chore: add extra bitshifts tests (noir-lang/noir#9680) feat: Propagate purities using SCCs (noir-lang/noir#9672) chore: break `NodeInterner` into chunks (noir-lang/noir#9674) fix(formatter): don't revert indentation increase after popping it (noir-lang/noir#9673) feat: hoist safe casts from loops (noir-lang/noir#9645) chore: fix clippy warnings (noir-lang/noir#9675) chore(ssa): Refactor flattening (noir-lang/noir#9663) chore(ssa): Greenlight `brillig_entry_points` and switch to centralized CallGraph (noir-lang/noir#9668) chore: add two mem2reg regression tests where references are returned (noir-lang/noir#9670) fix(mem2reg): reuse existing expression and add missing alias (noir-lang/noir#9664) chore: add tests for bounded_vec (noir-lang/noir#9576) chore: redact debug info and file maps from snapshots (noir-lang/noir#9666) chore: pull out interpreter binary evaluation logic into pure functions (noir-lang/noir#9665) feat: brillig functions can be pure if they are not entry points (noir-lang/noir#9659) END_COMMIT_OVERRIDE Co-authored-by: Tom French <15848336+TomAFrench@users.noreply.github.com>

Automated pull of nightly from the [noir](https://github.com/noir-lang/noir) programming language, a dependency of Aztec. BEGIN_COMMIT_OVERRIDE chore: remove duplicated frontend tests (noir-lang/noir#9706) chore: remove playwright workaround (noir-lang/noir#9704) fix(licm): Use `Loop::header` in `Loop::is_fully_executed` (noir-lang/noir#9700) chore: show which type is invalid as program input (noir-lang/noir#9701) chore: bump deps (noir-lang/noir#9698) chore: bump external pinned commits (noir-lang/noir#9693) chore(licm): Break things up further in LICM (noir-lang/noir#9683) chore(docs): spinning out bb docs (noir-lang/noir#9402) fix(ssa)!: Signed shift overflow checks rhs < bit_size (noir-lang/noir#9685) chore: add extra bitshifts tests (noir-lang/noir#9680) feat: Propagate purities using SCCs (noir-lang/noir#9672) chore: break `NodeInterner` into chunks (noir-lang/noir#9674) fix(formatter): don't revert indentation increase after popping it (noir-lang/noir#9673) feat: hoist safe casts from loops (noir-lang/noir#9645) chore: fix clippy warnings (noir-lang/noir#9675) chore(ssa): Refactor flattening (noir-lang/noir#9663) chore(ssa): Greenlight `brillig_entry_points` and switch to centralized CallGraph (noir-lang/noir#9668) chore: add two mem2reg regression tests where references are returned (noir-lang/noir#9670) fix(mem2reg): reuse existing expression and add missing alias (noir-lang/noir#9664) chore: add tests for bounded_vec (noir-lang/noir#9576) chore: redact debug info and file maps from snapshots (noir-lang/noir#9666) chore: pull out interpreter binary evaluation logic into pure functions (noir-lang/noir#9665) feat: brillig functions can be pure if they are not entry points (noir-lang/noir#9659) END_COMMIT_OVERRIDE

github-actions bot added the documentation Improvements or additions to documentation label Aug 5, 2025

signorecello marked this pull request as draft August 5, 2025 14:32

github-advanced-security bot found potential problems Aug 5, 2025

View reviewed changes

docs/tests/browser.test.ts Fixed Show fixed Hide fixed

github-actions bot reviewed Aug 5, 2025

View reviewed changes

signorecello marked this pull request as ready for review August 14, 2025 13:21

github-advanced-security bot found potential problems Aug 18, 2025

View reviewed changes

.github/workflows/docs-test.yml Fixed Show fixed Hide fixed

signorecello force-pushed the zkpedro/bb_docs branch 2 times, most recently from dfe7eef to a770763 Compare August 18, 2025 11:19

github-actions bot reviewed Aug 18, 2025

View reviewed changes

signorecello added 4 commits August 19, 2025 12:35

conflicts

6bd38b5

playwright

717c147

chore: cspell

401a17c

fix link

eaf196c

signorecello force-pushed the zkpedro/bb_docs branch from c86295d to eaf196c Compare August 19, 2025 11:35

signorecello requested a review from a team August 19, 2025 11:56

TomAFrench reviewed Aug 19, 2025

View reviewed changes

Savio-Sou reviewed Aug 19, 2025

View reviewed changes

docs/docs/getting_started/quick_start.md Outdated Show resolved Hide resolved

Savio-Sou reviewed Aug 19, 2025

View reviewed changes

docs/docs/getting_started/quick_start.md Outdated Show resolved Hide resolved

Savio-Sou reviewed Aug 19, 2025

View reviewed changes

docs/docs/getting_started/quick_start.md Outdated Show resolved Hide resolved

Savio-Sou reviewed Aug 19, 2025

View reviewed changes

docs/docs/tutorials/noirjs_app.md Show resolved Hide resolved

signorecello and others added 2 commits August 19, 2025 17:14

applying suggestions

214ecf8

Apply suggestions from code review

12dc720

Co-authored-by: Savio <72797635+Savio-Sou@users.noreply.github.com>

github-actions bot reviewed Aug 19, 2025

View reviewed changes

signorecello added 2 commits August 19, 2025 17:28

ci

9f35f26

ci

9e9bdf8

TomAFrench reviewed Aug 19, 2025

View reviewed changes

examples/docs_tutorials/browser/test.sh Outdated Show resolved Hide resolved

TomAFrench reviewed Aug 19, 2025

View reviewed changes

critesjosh approved these changes Aug 19, 2025

View reviewed changes

Update examples/docs_tutorials/browser/test.sh

d98c7f7

Savio-Sou approved these changes Aug 20, 2025

View reviewed changes

Savio-Sou enabled auto-merge August 20, 2025 14:05

Savio-Sou added this pull request to the merge queue Aug 20, 2025

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Aug 20, 2025

Savio-Sou and others added 6 commits August 20, 2025 16:05

Merge branch 'master' into zkpedro/bb_docs

5e3fd57

patching playwright version

0384256

patching playwright version

5ed5c16

yarn lock

a7f0158

playwright bad

26bf63f

Merge branch 'master' into zkpedro/bb_docs

ccd00bb

signorecello added this pull request to the merge queue Aug 25, 2025

github-merge-queue bot removed this pull request from the merge queue due to failed status checks Aug 25, 2025

signorecello added 2 commits August 25, 2025 21:07

Adding the test.sh file back

342cead

needs script for status check

e2d8c95

Savio-Sou added this pull request to the merge queue Aug 29, 2025

Merged via the queue into master with commit e5bd638 Aug 29, 2025
122 checks passed

Savio-Sou deleted the zkpedro/bb_docs branch August 29, 2025 18:01

AztecBot mentioned this pull request Aug 30, 2025

chore: Bump Noir reference AztecProtocol/aztec-packages#16649

Merged

Conversation

signorecello commented Aug 5, 2025

Summary

Key Changes

🏗️ New Dev Container Documentation

🧪 Playwright Browser Testing Infrastructure

🔗 Barretenberg Documentation

🛠️ Code Documentation Integration

🧹 Content Cleanup

Uh oh!

signorecello commented Aug 5, 2025

Uh oh!

Uh oh!

github-actions bot commented Aug 5, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

⚠️ Performance Alert ⚠️

Uh oh!

Uh oh!

socket-security bot commented Aug 18, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

⚠️ Performance Alert ⚠️

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Savio-Sou commented Aug 19, 2025

Uh oh!

signorecello commented Aug 19, 2025

Uh oh!

github-actions bot left a comment

Choose a reason for hiding this comment

⚠️ Performance Alert ⚠️

Uh oh!

signorecello commented Aug 19, 2025

Uh oh!

Uh oh!

TomAFrench left a comment

Choose a reason for hiding this comment

Uh oh!

critesjosh left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Savio-Sou commented Aug 20, 2025

Uh oh!

Uh oh!

github-actions bot commented Aug 25, 2025

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

github-actions bot commented Aug 5, 2025 •

edited

Loading

github-actions bot left a comment •

edited

Loading

socket-security bot commented Aug 18, 2025 •

edited

Loading

critesjosh left a comment •

edited

Loading