feat: `forge doc`

[rkrasiuk]

Component

Forge

Describe the feature you would like

This feature request is a tracker for forge doc subcommand that, given the solidity source files, generates an mdbook-like documentation with an option to serve it.

Tasks:

• [ ] create a doc crate with sample doc output struct
• [ ] reuse fmt's Visitor for parsing source files
• [ ] create default templates
• [ ] render the doc output into templates

References:

• docs.rs
• solidity-codegen
• mdBook
• dodoc
• askama
• tera

Additional context

No response

[transmissions11]

another (better imo) reference: https://github.com/primitivefinance/primitive-dodoc

[rkrasiuk]

nice find! including into the list

[0xYYY]

taking a look at this, currently working on a proof of concept, will send PR later to start discussion on details

[odyslam]

https://github.com/ZeframLou/foundry-docgen

[onbjerg]

See my comment here on ideas I had for forge doc: https://github.com/foundry-rs/foundry/issues/1410#issuecomment-1109824780

Also see the original issue: https://github.com/foundry-rs/foundry/issues/1410#issue-1214179443

I've closed that issue to roll it up into this one

[rkrasiuk]

Outstanding items for #2701:

• [x] Render top level funcs/structs/events. Currently, forge doc renders only contracts and all it's children items as the output. Provide a way to handle other top level items.
• [ ] Test coverage for DocParser & DocBuilder
• [x] Merge DocConfig with foundry config
• [ ] Add contributor docs to the doc crate (that's on me)
• [ ] Investigate unreachable items https://github.com/foundry-rs/foundry/blob/d9965ef65cab71a96a5efaa5e88c3800634e277c/doc/src/as_code.rs#L94-L97
• [x] Clean up code

[samlaf]

+1. Would really like to use this feature. In the meantime, I'm using https://github.com/OpenZeppelin/solidity-docgen combined with https://book.getfoundry.sh/config/hardhat, but it would be nice not to have to pollute our project with hardhat stuff only for generating documentation.