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: #1410 (comment)

Also see the original issue: #1410 (comment)

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

[rkrasiuk]

Outstanding items for #2701:

• 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
• Merge DocConfig with foundry config
• Add contributor docs to the doc crate (that's on me)
• Investigate unreachable items
  

  foundry/doc/src/as_code.rs

  Lines 94 to 97 in d9965ef

  	item => {
  	println!("UNREACHABLE {:?}", item); // TODO:
  	unreachable!()
  	}

• 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.