search

foundry-rs / foundry

Foundry is a blazing fast, portable and modular toolkit for Ethereum application development written in Rust.
https://getfoundry.sh
Apache License 2.0
8.29k stars 1.75k forks source link

meta(doc): tracking issue for `forge doc` improvements #4115

Open transmissions11 opened 1 year ago

transmissions11 commented 1 year ago

Features:

  1. Resolve relative image imports in home properly

When testing forge doc w/ Art Gobblers the home page shows up like this:

image

The broken images seem to be due to the fact that the Art Gobblers readme uses relative imports like ![Gobbler Lifecycle](assets/state-machines/gobbler-lifecycle.png) for images which work on Github but not with forge doc. Would be nice if they were as 1:1 compatible as possible.

  1. More eager link resolving

i.e: Links in the author section do not get shown as hyperlinks:

image

  1. Table of contents sidebar for each file/contract

Would make it a lot easier to navigate large contracts' docs if there was a table of contents on sidebar that had a collapsable header for functions, events, errors, etc and you could open them to skip to specific functions/events/errors/etc.

spengrah commented 1 year ago

I'm also loving forge doc! I was gonna create a new issue with a couple things I noticed, but figured I'd leave them here since this issue is already scoped broadly

  1. +1 on table of contents sidebar

  2. User-defined SUMMARY.md. Just like a user can provide their own settings for the book by specifying a path for book.toml, it would be great to be able to define book layout by specifying a path for a custom SUMMARY.md file.

  3. Support for extra-watch-dirs. This would be useful for allowing projects to include more detailed docs and guides outside of the project readme and NatSpec.

mds1 commented 1 year ago

Agree with everything here. Only comment is on @slgraham third item: Perhaps instead of extra-watch-dirs, we just put those additional docs in the same docs folder that gets created by forge doc. Might need to move all the autogenerated stuff into a subfolder like docs/docgen so it's easy to commit the custom SUMMARY.md and other custom files while not comitting the generated docs. And the SUMMARY.md file would specify what to do with your custom files

syahrul12345 commented 1 year ago

Hey guys, are there any workarounds for this ?

zerosnacks commented 4 months ago

From: https://github.com/foundry-rs/foundry/issues/4241 by @alexange

All free functions (including custom errors) are exported with their own markdown file, leading to a lot of singular pages with only one piece of code. Since they are not defined within an interface or contract but they are within a solidity file, there should be a singular markdown file exported for each solidity file which includes all of its free functions, constants and custom errors.

Free constants are already exported to a dedicated "constants" file with the solidity file name, so this should just be extended to include all free functions and variables.