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.
Even 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.
How to do it
Bad options
Simple include_str!
A simple way to do this would just be to add:
#![doc = include_str!("../../README.md")]
However the first section with all the badges break. So I don't think this is a good option.
include-utils
There is a crate, include-utils, 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.
However, 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.
So, I don't think this is a great option either.
Good options
Custom build.rs handling to filter the file
Instead 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.
The downside here is a bit of added complexity, but I don't mind knocking it out if desired.
Move most of docs into crate docs, use cargo-readme
The 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 lets us generate the markdown README from those.
This has the added benefit of making it really easy to add cross-linking to types and functions inside the crate docs, which is nice.
The 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?
We have a fairly rich README in the repository, but very minimalist
lambda-runtimedocs (same goes forlambda-extension, but i thinklambda-runtimeis most important). I know the README already shows in GitHub, and oncrates.io, butdocs.rsadds discoverability as well. It gives the impression that the crate is well-maintained (which it is), whereas sparsedocs.rsdocs don't look so great.Even 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.How to do it
Bad options
Simple
include_str!A simple way to do this would just be to add:
However the first section with all the badges break. So I don't think this is a good option.
include-utilsThere is a crate, include-utils, 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.
However, 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.
So, I don't think this is a great option either.
Good options
Custom
build.rshandling to filter the fileInstead 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.The downside here is a bit of added complexity, but I don't mind knocking it out if desired.
Move most of docs into crate docs, use
cargo-readmeThe 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 lets us generate the markdown
READMEfrom those.This has the added benefit of making it really easy to add cross-linking to types and functions inside the crate docs, which is nice.
The 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?