René's URL Explorer Experiment

{"@context":"https://schema.org","@type":"DiscussionForumPosting","headline":"[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates","articleBody":"We have a fairly rich README in the repository, but very minimalist `lambda-runtime` docs (same goes for `lambda-extension`, but i think `lambda-runtime` is most important). I know the README already shows in GitHub, and on `crates.io`, but `docs.rs` adds discoverability as well. It gives the impression that the crate is well-maintained (which it is), whereas sparse `docs.rs` docs don't look so great.\n\nEven without a full from-scratch crate docs write, I think it would add a lot of value to make some of the content in the README show up in `docs.rs`. \n\n## How to do it\n### Bad options\n#### Simple `include_str!`\nA simple way to do this would just be to add:\n```\n#![doc = include_str!(\"../../README.md\")]\n```\n\nHowever the first section with all the badges break. So I don't think this is a good option.\n\n#### `include-utils`\nThere is a crate, [include-utils](https://docs.rs/include-utils/latest/include_utils/index.html), that does pretty much exactly what we need. It would allow only including a subset of the file, so we would include everything after the first section.\n\nHowever, it would force a new proc macro-based dependency into our primary dependencies, which I don't love. It also seems maintained but is not widely used.\n\nSo, I don't think this is a great option either.\n\n### Good options\n#### Custom `build.rs` handling to filter the file\nInstead of using the proc macro, we could also just filter the file into what we need via a custom `build.rs`. This is nice too since then we could replace the badges with regular links to the related crates, which would be kind of nice.\n\nThe downside here is a bit of added complexity, but I don't mind knocking it out if desired.\n\n#### Move most of docs into crate docs, use `cargo-readme`\nThe other good option is to flip things around and migrate the source of truth to be the library docs proper. Then the tool [cargo-readme](https://github.com/webern/cargo-readme) lets us generate the markdown `README` from those.\n\nThis has the added benefit of making it really easy to add cross-linking to types and functions inside the crate docs, which is nice.\n\nThe downside is that now we need to generate README changes via an extra build step. I guess we could add a pre-commit hook to do it so that nobody forgets?\n","author":{"url":"https://github.com/jlizen","@type":"Person","name":"jlizen"},"datePublished":"2025-05-08T15:40:34.000Z","interactionStatistic":{"@type":"InteractionCounter","interactionType":"https://schema.org/CommentAction","userInteractionCount":0},"url":"https://github.com/990/aws-lambda-rust-runtime/issues/990"}