aws / aws/aws-lambda-rust-runtime

[Docs] Pull content from README into `lambda-runtime` crate docs / other readmes into other crates

未关闭
#990 0 条评论 0 个 reaction 已指派 0 人 在 GitHub 查看
主要语言
Rust
星标
3.6k
派生
396
PR 合并指标
30 天内没有已合并 PR

描述

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](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.

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](https://github.com/webern/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?

贡献指南

打开贡献指南

调研方向

首先阅读仓库README和现有的lambda-runtime crate文档,然后比较所提议的include_str!、自定义build.rs和cargo-readme方案。当lambda-runtime的docs.rs中出现有用的README内容,并且为lambda-extension及其他crate的README确定了经过审慎考虑的路径,适当地保留或替换徽章部分时,工作就完成了。

由索引模型根据 Issue 内容生成。

评估

技术栈
rust
领域
documentation
Issue 类型
文档
难度
5/5
预计耗时
一周以上
活跃度
停滞
描述清晰度
基本清楚
新手友好度
35/100

把新 issue 发到你的邮箱

精选适合新手参与的 GitHub issue 摘要。