foundry-rs / foundry-rs/foundry
meta(docs): clean up developer documentation
- Dominant language
- Rust
- Stars
- 10.6k
- Forks
- 2.6k
- Avg merge
- 18h 20m
- Merged PRs (30d)
- 510
Description
## context
the workspace changed quite a bit since #13880 was opened. `wallets` moved to `foundry-core`, `solar` and `tui` were added, and there are more crates under `evm/`. manually documenting every crate and its dependencies in one file will probably become outdated again pretty quickly.
as @zerosnacks mentioned in https://github.com/foundry-rs/foundry/issues/13880#issuecomment-4161052129, i think it is higher leverage to remove this page and improve the generated crate docs and the book incrementally.
there are a few other things to clean up at the same time:
- `docs/dev/README.md` is linked as the developer guidelines, but it still says that it is incomplete and possibly outdated;
- the index does not include existing pages like `lintrules.md`, `output-channels.md`, and `showmap.md`;
- it is not very clear what should live in `docs/dev`, Rustdoc, the book, `CONTRIBUTING.md`, or `AGENTS.md`;
- some instructions are duplicated between these places and can drift;
- crate-level Rustdoc exists for the whole workspace, but some crate landing pages still have very little context.
i think the split should roughly be:
- user-facing guides, config and CLI documentation belong in the [book](https://getfoundry.sh/);
- crate/module internals and APIs belong in the source as Rustdoc and are published at https://foundry-rs.github.io/foundry/;
- cross-crate contributor workflows and invariants can stay in `docs/dev` or `CONTRIBUTING.md`;
- agent-specific instructions should stay in `AGENTS.md`, but link to the canonical docs instead of duplicating them;
- release-facing changes should use `.changelog` and the generated changelog/release notes.
## work
- [x] remove `docs/dev/architecture.md` and its entry from the developer docs index;
- [x] clean up `docs/dev/README.md` and make it an accurate index of the contributor documentation we actually maintain;
- [x] audit the existing `docs/dev/*.md` files and decide which ones should stay, be updated, move somewhere else, or be removed;
- [x] link the developer docs to the book, generated Rustdoc, `CONTRIBUTING.md`, and the changelog instructions;
- [x] reduce duplicated guidance between `docs/dev`, `CONTRIBUTING.md`, and `AGENTS.md`;
- [x] improve crate-level Rustdoc overviews incrementally where they are missing useful context;
- [x] open focused issues in `foundry-rs/book` for concrete user-facing gaps instead of tracking a general book rewrite here;
- [x] close #13880 as superseded by this issue.
i don't think we should remove all of `docs/dev`. pages like `cheatcodes.md`, `output-channels.md`, and `showmap.md` are still actively maintained. the goal is mostly to remove the stale parts and make the ownership of the remaining docs clearer.
Contributor guide
Assessment
This issue has not been assessed yet.