feat(forge): doc

[rkrasiuk]

Motivation

Implementation of forge doc described in #1675

Solution

The forge doc command parses the source contracts and generates markdown files under <root>/docs. These files can be served by running forge doc --serve.

See README for more details on the architecture of the doc module

[mattsse]

+1 on making doc a crate, let's try to move as much of the logic there,

ideally, there should be some kind of Builder, or function that accepts a config and will handle it from there.

[sambacha]

is it possible to add pandoc attribute headers here too?
see pandoc docs about attr headers

Also, idk if you may find this useful reference https://github.com/sambacha/go-natspec , would like to see forge doc as a separate binary if possible (if its a separate crate this should be the case correct?)

[mattsse]

only did a high level review, just because this is quite huge, but it's very readable and you can understand how this is supposed to work just by reading this.

smol nits, otherwise lgtm

[emo-eth]

Running on the Seaport 1.2 branch results in a rather unhelpful error:

❯ forge doc --serve
Error: 
Failed to parse source: unknown comment tag: 

[sambacha]

https://github.com/foundry-rs/foundry/blob/7c135cd969092710ad53d2532c3113a9a4517344/doc/src/writer/markdown.rs#L21:5

Only FencedCodeBlock, as there are two different kinds of Code Blocks: Fenced and Indentation based. I don't think you want to support Indentation-based code blocks for generated output.

Can we add reference links for each natspec section back to the relevant source lineos?

[gakonst]

Absolutely incredible. Would prefer if we used Axum instead of Warp. Love the Preprocessor keeping things clean.