feat: nargo doc

[asterite]

Description

Problem

Will help with building aztec-nr docs, and any package docs in general.

Summary

This PR started as a new command to generate a JSON that would help build docs.

Then it produced a single Markdown file from that JSON output (or, well, from the Rust types representing that JSON).

Eventually, and this is the final form of this PR, it morphed into generating HTML files (with a stylesheet) to navigate the docs.

Here are example docs built from the aztec-nr repository: https://asterite.github.io/aztec-nr-docs/index.html

Features:

• Docs layout is similar to rustdoc
• Inter-linking between types
• Documentation for dependencies is also generated, so you can navigate to any type via links (even stdlib types and primitive types)
• Has a style similar to the lightweight theme of rustdoc
• Has a navbar which is similar to the one in rustdoc (lets you quickly jump to sections in the current item, or in the parent item)
• Has an "All items" section that lists all items (excluding depenedencies). This can also serve as a basic search functionality (search via the browser).

Note: the docs won't look very complete at this point but that's because aztec-nr lacks doc comments. There are some, but ideally every module and item is documented there, with examples, etc.

Additional Context

The large diff is because we now commit the generated stdlib docs.

Documentation

Check one:

• No documentation needed.
• Documentation included in this PR.
• [For Experimental Features] Documentation to be submitted in a separate PR.

PR Checklist

• I have tested the changes locally.
• I have formatted the changes with Prettier and/or cargo fmt on default settings.

[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: ae001a3	Previous: 65a8fb0	Ratio
test_report_zkpassport_noir_rsa_	2 s	1 s	2

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

CC: @TomAFrench

[socket-security]

No dependency changes detected. Learn more about Socket for GitHub.

👍 No dependency changes detected in pull request

[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: 3384c75	Previous: dbe4d81	Ratio
sha512-100-bytes	0.087 s	0.055 s	1.58

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

CC: @TomAFrench

[asterite]

I recently realized some types like Add or Mul didn't have links. It turns out they are re-exported, and the tool didn't analyze re-exports. This turned out to be even more important because for example compressed_string consists of a single re-export of a private item, so it was previously not shown. Or for example noir_aztec re-exports protocol_types, and without that information you wouldn't know you can access that via aztec-nr (so the docs wouldn't be that useful, really).

[TomAFrench]

I took a quick look at getting the dead link checking up but it seems like a lot of tools are just set up for markdown and supposedly a lot of the ones which work on html files aren't maintained or complete.

I think in the meantime we can just remove the committed output and revisit in the future. We can keep things as a snapshot test to ensure that we don't completely wreck it as stdlib changes should be rare.

We can have a build of the stdlib docs pushed to gh_pages in a separate PR.

[jfecher]

Very cool!