[Docs] Pull content from README into lambda-runtime crate docs

[jlizen]

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?